[hornetq-commits] JBoss hornetq SVN: r8769 - in trunk: docs/user-manual/en and 6 other directories.

Author: jmesnil Date: 2010-01-07 09:48:27 -0500 (Thu, 07 Jan 2010) New Revision: 8769 Added: trunk/src/main/org/hornetq/spi/core/logging/package-info.java trunk/src/main/org/hornetq/spi/core/security/package-info.java Modified: trunk/build-hornetq.xml trunk/docs/user-manual/en/perf-tuning.xml trunk/docs/user-manual/en/send-guarantees.xml trunk/src/main/org/hornetq/api/core/Interceptor.java trunk/src/main/org/hornetq/api/core/Pair.java trunk/src/main/org/hornetq/api/core/TransportConfiguration.java trunk/src/main/org/hornetq/api/core/client/ClientProducer.java trunk/src/main/org/hornetq/api/core/client/ClientSession.java trunk/src/main/org/hornetq/api/core/client/ClientSessionFactory.java trunk/src/main/org/hornetq/api/core/client/HornetQClient.java trunk/src/main/org/hornetq/api/core/client/SendAcknowledgementHandler.java trunk/src/main/org/hornetq/api/core/client/SessionFailureListener.java trunk/src/main/org/hornetq/api/core/client/loadbalance/FirstElementConnectionLoadBalancingPolicy.java trunk/src/main/org/hornetq/api/core/client/loadbalance/RandomConnectionLoadBalancingPolicy.java trunk/src/main/org/hornetq/api/core/client/loadbalance/RoundRobinConnectionLoadBalancingPolicy.java trunk/src/main/org/hornetq/api/core/client/loadbalance/package-info.java trunk/src/main/org/hornetq/api/core/client/package-info.java trunk/src/main/org/hornetq/api/core/package-info.java trunk/src/main/org/hornetq/api/jms/package-info.java Log: javadoc fixes Modified: trunk/build-hornetq.xml =================================================================== --- trunk/build-hornetq.xml 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/build-hornetq.xml 2010-01-07 14:48:27 UTC (rev 8769) @@ -1019,7 +1019,7 @@ <classpath refid="javadoc.classpath"/> <doctitle><![CDATA[<h2>HornetQ ${module.version}</h2>]]></doctitle> <bottom><![CDATA[<i>Copyright &#169; 2009 Red Hat Inc. All Rights Reserved.</i>]]></bottom> - <group title="HornetQ Core" packages="org.hornetq.api, org.hornetq.api.core.*"/> + <group title="HornetQ Core" packages="org.hornetq.api, org.hornetq.api.core, org.hornetq.api.core.*"/> <group title="JMS" packages="org.hornetq.api.jms, org.hornetq.api.jms.*"/> <group title="HornetQ SPI" packages="org.hornetq.spi.*"/> <link href="http://java.sun.com/j2se/1.5.0/docs/api"/> Modified: trunk/docs/user-manual/en/perf-tuning.xml =================================================================== --- trunk/docs/user-manual/en/perf-tuning.xml 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/docs/user-manual/en/perf-tuning.xml 2010-01-07 14:48:27 UTC (rev 8769) @@ -116,7 +116,7 @@ <listitem> <para>Use pre-acknowledge mode. With pre-acknowledge mode, messages are acknowledged <literal>before</literal> they are sent to the client. This reduces the - amount of acknowledgment traffic on the wire. For more information on this, see + amount of acknowledgement traffic on the wire. For more information on this, see <xref linkend="pre-acknowledge"/>.</para> </listitem> <listitem> Modified: trunk/docs/user-manual/en/send-guarantees.xml =================================================================== --- trunk/docs/user-manual/en/send-guarantees.xml 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/docs/user-manual/en/send-guarantees.xml 2010-01-07 14:48:27 UTC (rev 8769) @@ -136,7 +136,7 @@ instance on your <literal>ClientSession</literal>.</para> <para>Then, you just send messages as normal using your <literal - back an acknowledgment of the send asynchronously, and some time later you are + back an acknowledgement of the send asynchronously, and some time later you are informed at the client side by HornetQ calling your handler's <literal reference to the message that was sent.</para> Modified: trunk/src/main/org/hornetq/api/core/Interceptor.java =================================================================== --- trunk/src/main/org/hornetq/api/core/Interceptor.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/Interceptor.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -13,13 +13,15 @@ package org.hornetq.api.core; +import org.hornetq.api.core.client.ClientSessionFactory; import org.hornetq.core.remoting.Packet; import org.hornetq.core.remoting.RemotingConnection; /** - * This is class is a simple way to intercepting server calls on HornetQ. + * This is class is a simple way to intercepting calls on HornetQ client and servers. * <p/> - * To Add this interceptor, you have to modify hornetq-configuration.xml + * To add an interceptor to HornetQ server, you have to modify hornetq-configuration.xml. + * To add it to a client, use {@link ClientSessionFactory#addInterceptor(Interceptor)} * * @author clebert.suconic(a)jboss.com * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a> @@ -27,12 +29,12 @@ public interface Interceptor { /** - * gets called when a packet is received prior to be sent to the channel + * Intercepts a packet which is received before it is sent to the channel * * @param packet the packet being received * @param connection the connection the packet was received on - * @return true to process the next interceptor and handle the packet, - * false to abort processing of the packet + * @return {@code true} to process the next interceptor and handle the packet, + * {@code false} to abort processing of the packet * @throws HornetQException */ boolean intercept(Packet packet, RemotingConnection connection) throws HornetQException; Modified: trunk/src/main/org/hornetq/api/core/Pair.java =================================================================== --- trunk/src/main/org/hornetq/api/core/Pair.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/Pair.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -17,7 +17,7 @@ /** * - * A Pair is basically a holder for 2 objects. + * A Pair is a holder for 2 objects. * * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a> * Modified: trunk/src/main/org/hornetq/api/core/TransportConfiguration.java =================================================================== --- trunk/src/main/org/hornetq/api/core/TransportConfiguration.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/TransportConfiguration.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -19,10 +19,10 @@ import org.hornetq.utils.UUIDGenerator; /** - * A TransportConfiguration is used by a client to specify a connections to a server and its back up if one exists.<br><br> + * A TransportConfiguration is used by a client to specify a connections to a server and its backup if one exists.<br><br> * <p/> - * Typically the constructors take the classname and paramaters for needed to create the connection. These will be - * different dependant on what connector is beingused i.e. Netty or InVM etc. An example:<br><br> + * Typically the constructors take the class name and parameters for needed to create the connection. These will be + * different dependent on which connector is being used, i.e. Netty or InVM etc. For example:<br><br> * <p/> * <code> * HashMap<String, Object> map = new HashMap<String, Object>();<br> @@ -82,10 +82,10 @@ /** * Creates a TransportConfiguration with a specific name providing the class name of the {@link org.hornetq.spi.core.remoting.ConnectorFactory} - * and any params needed. + * and any parameters needed. * * @param className The class name of the ConnectorFactory - * @param params The params needed by the ConnectorFactory + * @param params The parameters needed by the ConnectorFactory * @param name The name of this TransportConfiguration */ public TransportConfiguration(final String className, final Map<String, Object> params, final String name) @@ -99,10 +99,10 @@ /** * Creates a TransportConfiguration providing the class name of the {@link org.hornetq.spi.core.remoting.ConnectorFactory} - * and any params needed. + * and any parameters needed. * * @param className The class name of the ConnectorFactory - * @param params The params needed by the ConnectorFactory + * @param params The parameters needed by the ConnectorFactory */ public TransportConfiguration(final String className, final Map<String, Object> params) { @@ -132,7 +132,7 @@ /** * Returns the class name of ConnectorFactory being used by this TransportConfiguration * - * @return The classname + * @return The factory's class name */ public String getFactoryClassName() { @@ -140,9 +140,9 @@ } /** - * Returns any params set for this TransportConfiguration + * Returns any parameters set for this TransportConfiguration * - * @return the params + * @return the parameters */ public Map<String, Object> getParams() { @@ -292,7 +292,7 @@ * <p/> * Note this is only used internally by HornetQ * - * @param buffer the biffer to decode from + * @param buffer the buffer to decode from */ public void decode(final HornetQBuffer buffer) { Modified: trunk/src/main/org/hornetq/api/core/client/ClientProducer.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/ClientProducer.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/ClientProducer.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -18,7 +18,7 @@ import org.hornetq.api.core.SimpleString; /** - * A ClientProducer is ised to send messages to a specific address. Messages are then routed on the server to any queues + * A ClientProducer is used to send messages to a specific address. Messages are then routed on the server to any queues * that are bound to the address. A ClientProducer can either be created with a specific address in mind or with none. * With the latter the address must be provided using the appropriate send() method. <br><br> * Modified: trunk/src/main/org/hornetq/api/core/client/ClientSession.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/ClientSession.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/ClientSession.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -40,15 +40,11 @@ { /** * Returns <code>true</code> if the binding exists, <code>false</code> else. - * - * @return <code>true</code> if the binding exists, <code>false</code> else */ boolean isExists(); /** * Returns the names of the queues bound to the binding. - * - * @return the names of the queues bound to the binding */ public List<SimpleString> getQueueNames(); } @@ -62,43 +58,31 @@ { /** * Returns <code>true</code> if the queue exists, <code>false</code> else. - * - * @return <code>true</code> if the queue exists, <code>false</code> else */ boolean isExists(); /** * Returns <code>true</code> if the queue is durable, <code>false</code> else. - * - * @return <code>true</code> if the queue is durable, <code>false</code> else */ boolean isDurable(); /** * Returns the number of consumers attached to the queue. - * - * @return the number of consumers attached to the queue */ int getConsumerCount(); /** * Returns the number of messages in the queue. - * - * @return the number of messages in the queue */ int getMessageCount(); /** * Returns the queue's filter string (or <code>null</code> if the queue has no filter). - * - * @return the queue's filter string (or <code>null</code> if the queue has no filter) */ SimpleString getFilterString(); /** * Returns the address that the queue is bound to. - * - * @return the address that the queue is bound to */ SimpleString getAddress(); } Modified: trunk/src/main/org/hornetq/api/core/client/ClientSessionFactory.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/ClientSessionFactory.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/ClientSessionFactory.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -55,10 +55,9 @@ /** * Creates a <em>non-transacted</em> session. - * - * Message sends and acknowledgments are automatically committed by the session. <em>This does not + * Message sends and acknowledgements are automatically committed by the session. <em>This does not * mean that messages are automatically acknowledged</em>, only that when messages are acknowledged, - * the session will automatically commit the transaction containing the acknowledgments. + * the session will automatically commit the transaction containing the acknowledgements. * @return a non-transacted ClientSession * @throws HornetQException if an exception occurs while creating the session Modified: trunk/src/main/org/hornetq/api/core/client/HornetQClient.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/HornetQClient.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/HornetQClient.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -20,10 +20,13 @@ import java.util.List; /** - * A utility class for creating core HornetQ ClientSessionFactory's. - * + * Utility class for creating HornetQ {@link ClientSessionFactory} objects. + * + * Once a {@link ClientSessionFactory} has been created, it can be further configured + * using its setter methods before creating the sessions. Once a session is created, + * the factory can no longer be modified (its setter methods will throw a {@link IllegalStateException}. + * * @author <a href="mailto:andy.taylor@jboss.org">Andy Taylor</a> - * Created Jan 5, 2010 */ public class HornetQClient { @@ -98,7 +101,7 @@ } /** - * Creates a new CLientSessionFactory using the same settings as the one passed in. + * Creates a new ClientSessionFactory using the same configuration as the one passed in. * * @param other The ClientSessionFactory to copy * @return The new ClientSessionFactory @@ -109,7 +112,7 @@ } /** - * Create a ClientSessionFactory that uses discovery to connect to the server. + * Creates a ClientSessionFactory that uses discovery to connect to the servers. * * @param discoveryAddress The address to use for discovery * @param discoveryPort The port to use for discovery. @@ -132,10 +135,10 @@ } /** - * Create a ClientConnectionFactory using a TransportConfiguration of the server and a backup if needed. + * Creates a ClientConnectionFactory using a TransportConfiguration of the server and a backup if needed. * * @param connectorConfig The TransportConfiguration of the server to connect to. - * @param backupConnectorConfig The TransportConfiguration of the backup server to connect to. can be null. + * @param backupConnectorConfig The TransportConfiguration of the backup server to connect to (or {@code null}�if there is no backup) * @return The ClientSessionFactory. */ public static ClientSessionFactory createClientSessionFactory(final TransportConfiguration connectorConfig, @@ -145,7 +148,7 @@ } /** - * Create a ClientSessionFactory using the TransportConfiguration of the server to connect to. + * Creates a ClientSessionFactory using the TransportConfiguration of the server to connect to. * * @param connectorConfig The TransportConfiguration of the server. * @return The ClientSessionFactory. Modified: trunk/src/main/org/hornetq/api/core/client/SendAcknowledgementHandler.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/SendAcknowledgementHandler.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/SendAcknowledgementHandler.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -18,8 +18,8 @@ /** * A SendAcknowledgementHandler notifies a client when an message sent asynchronously has been received by the server. * <br /> - * If the session is not blocking when sending durable or non-durbale messages, the session can - * set a SendAcknowledgementHandler to ben notified later when the messages + * If the session is not blocking when sending durable or non-durable messages, the session can + * set a SendAcknowledgementHandler to be notified later when the messages * has been received by the server. The method {@code sendAcknowledged} will be called with the message that * was sent asynchronously. * Modified: trunk/src/main/org/hornetq/api/core/client/SessionFailureListener.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/SessionFailureListener.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/SessionFailureListener.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -17,7 +17,7 @@ import org.hornetq.core.remoting.FailureListener; /** - * A SessionFailureListener notifies the client when a failure occured on the session. + * A SessionFailureListener notifies the client when a failure occurred on the session. * * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a> */ Modified: trunk/src/main/org/hornetq/api/core/client/loadbalance/FirstElementConnectionLoadBalancingPolicy.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/loadbalance/FirstElementConnectionLoadBalancingPolicy.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/loadbalance/FirstElementConnectionLoadBalancingPolicy.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -15,13 +15,11 @@ /** - * A FirstElementConnectionLoadBalancingPolicy + * A {@link FirstElementConnectionLoadBalancingPolicy#select(int)} always returns 0. * * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a> * * Created 28 Nov 2008 10:56:59 - * - * */ public class FirstElementConnectionLoadBalancingPolicy implements ConnectionLoadBalancingPolicy { Modified: trunk/src/main/org/hornetq/api/core/client/loadbalance/RandomConnectionLoadBalancingPolicy.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/loadbalance/RandomConnectionLoadBalancingPolicy.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/loadbalance/RandomConnectionLoadBalancingPolicy.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -16,7 +16,7 @@ import org.hornetq.utils.Random; /** - * A RandomConnectionLoadBalancingPolicy + * {@link RandomConnectionLoadBalancingPolicy#select(int)} returns a random integer between {@code 0} (inclusive) and {@code max} (exclusive) * * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a> * Modified: trunk/src/main/org/hornetq/api/core/client/loadbalance/RoundRobinConnectionLoadBalancingPolicy.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/loadbalance/RoundRobinConnectionLoadBalancingPolicy.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/loadbalance/RoundRobinConnectionLoadBalancingPolicy.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -16,7 +16,11 @@ import org.hornetq.utils.Random; /** - * A RoundRobinConnectionLoadBalancingPolicy + * RoundRobinConnectionLoadBalancingPolicy corresponds to a round-robin load-balancing policy. + * + * <br> + * The first call to {@link #select(int)} will return a random integer between {@code 0} (inclusive) and {@code max}�(exclusive). + * Subsequent calls will then return an integer in a round-robin fashion. * * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a> * Modified: trunk/src/main/org/hornetq/api/core/client/loadbalance/package-info.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/loadbalance/package-info.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/loadbalance/package-info.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -12,7 +12,11 @@ */ /** - * HornetQ client side connection load balancing policies + * Client load-balancing API. + * <br> + * This package defines the policies supported by + * HornetQ to load-balance client connections across + * HornetQ servers. */ package org.hornetq.api.core.client.loadbalance; Modified: trunk/src/main/org/hornetq/api/core/client/package-info.java =================================================================== --- trunk/src/main/org/hornetq/api/core/client/package-info.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/client/package-info.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -12,7 +12,7 @@ */ /** - * HornetQ core client messaging API to produce and consume messages. + * Core Client Messaging API. * <br> * This package defines the API used by HornetQ clients to produce and consume messages. */ Modified: trunk/src/main/org/hornetq/api/core/package-info.java =================================================================== --- trunk/src/main/org/hornetq/api/core/package-info.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/core/package-info.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -12,9 +12,10 @@ */ /** - * HornetQ core messaging API + * Core Messaging API. * <br> - * This package defines the core API + * This package defines base classes and interfaces used + * throughout HornetQ API */ package org.hornetq.api.core; Modified: trunk/src/main/org/hornetq/api/jms/package-info.java =================================================================== --- trunk/src/main/org/hornetq/api/jms/package-info.java 2010-01-07 13:52:32 UTC (rev 8768) +++ trunk/src/main/org/hornetq/api/jms/package-info.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -12,7 +12,10 @@ */ /** - * This package contains classes that relate to the HornetQ JMS implementation + * API to create HornetQ JMS resources. + * <br> + * This package contains classes to create + * HornetQ JMS managed resources (ConnectionFactory, Queue and Topic). * */ package org.hornetq.api.jms; Added: trunk/src/main/org/hornetq/spi/core/logging/package-info.java =================================================================== --- trunk/src/main/org/hornetq/spi/core/logging/package-info.java (rev 0) +++ trunk/src/main/org/hornetq/spi/core/logging/package-info.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -0,0 +1,21 @@ +/* + * Copyright 2009 Red Hat, Inc. + * Red Hat licenses this file to you under the Apache License, version + * 2.0 (the "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * http://www.apache.org/licenses/LICENSE-2.0 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + * implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +/** + * Logging SPI. + * <br> + * This package defines the Service Provide Interface to + * support different logging implementation. + */ +package org.hornetq.spi.core.logging; + Added: trunk/src/main/org/hornetq/spi/core/security/package-info.java =================================================================== --- trunk/src/main/org/hornetq/spi/core/security/package-info.java (rev 0) +++ trunk/src/main/org/hornetq/spi/core/security/package-info.java 2010-01-07 14:48:27 UTC (rev 8769) @@ -0,0 +1,22 @@ +/* + * Copyright 2009 Red Hat, Inc. + * Red Hat licenses this file to you under the Apache License, version + * 2.0 (the "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * http://www.apache.org/licenses/LICENSE-2.0 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + * implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +/** + * Security SPI. + * <br> + * This package defines the Service Provide Interface + * that secuity providers can implement to plug their + * implementation into HornetQ. + */ +package org.hornetq.spi.core.security; +