activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tab...@apache.org
Subject svn commit: r1388313 - in /activemq/trunk/activemq-core/src/main/java/org/apache/activemq: ActiveMQConnection.java ActiveMQConnectionFactory.java util/URISupport.java
Date Fri, 21 Sep 2012 03:31:14 GMT
Author: tabish
Date: Fri Sep 21 03:31:13 2012
New Revision: 1388313

URL: http://svn.apache.org/viewvc?rev=1388313&view=rev
Log:
fix for: https://issues.apache.org/jira/browse/AMQ-730

Update some JavaDocs

Modified:
    activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnection.java
    activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnectionFactory.java
    activemq/trunk/activemq-core/src/main/java/org/apache/activemq/util/URISupport.java

Modified: activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnection.java
URL: http://svn.apache.org/viewvc/activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnection.java?rev=1388313&r1=1388312&r2=1388313&view=diff
==============================================================================
--- activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnection.java
(original)
+++ activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnection.java
Fri Sep 21 03:31:13 2012
@@ -1690,10 +1690,10 @@ public class ActiveMQConnection implemen
     }
 
     /**
-     * If this flag is set then a separate thread is not used for dispatching
-     * messages for each Session in the Connection. However, a separate thread
-     * is always used if there is more than one session, or the session isn't in
-     * auto acknowledge or duplicates ok mode
+     * If this flag is not set then a separate thread is not used for dispatching messages
for each Session in
+     * the Connection. However, a separate thread is always used if there is more than one
session, or the session
+     * isn't in auto acknowledge or duplicates ok mode.  By default this value is set to
true and session dispatch
+     * happens asynchronously.
      */
     public void setAlwaysSessionAsync(boolean alwaysSessionAsync) {
         this.alwaysSessionAsync = alwaysSessionAsync;

Modified: activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnectionFactory.java
URL: http://svn.apache.org/viewvc/activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnectionFactory.java?rev=1388313&r1=1388312&r2=1388313&view=diff
==============================================================================
--- activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnectionFactory.java
(original)
+++ activemq/trunk/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnectionFactory.java
Fri Sep 21 03:31:13 2012
@@ -830,10 +830,10 @@ public class ActiveMQConnectionFactory e
     }
 
     /**
-     * If this flag is set then a separate thread is not used for dispatching
-     * messages for each Session in the Connection. However, a separate thread
-     * is always used if there is more than one session, or the session isn't in
-     * auto acknowledge or duplicates ok mode
+     * If this flag is not set then a separate thread is not used for dispatching messages
for each Session in
+     * the Connection. However, a separate thread is always used if there is more than one
session, or the session
+     * isn't in auto acknowledge or duplicates ok mode.  By default this value is set to
true and session dispatch
+     * happens asynchronously.
      */
     public void setAlwaysSessionAsync(boolean alwaysSessionAsync) {
         this.alwaysSessionAsync = alwaysSessionAsync;

Modified: activemq/trunk/activemq-core/src/main/java/org/apache/activemq/util/URISupport.java
URL: http://svn.apache.org/viewvc/activemq/trunk/activemq-core/src/main/java/org/apache/activemq/util/URISupport.java?rev=1388313&r1=1388312&r2=1388313&view=diff
==============================================================================
--- activemq/trunk/activemq-core/src/main/java/org/apache/activemq/util/URISupport.java (original)
+++ activemq/trunk/activemq-core/src/main/java/org/apache/activemq/util/URISupport.java Fri
Sep 21 03:31:13 2012
@@ -29,9 +29,16 @@ import java.util.Map;
 
 /**
  * Utility class that provides methods for parsing URI's
+ *
+ * This class can be used to split composite URI's into their component parts and is used
to extract any
+ * URI options from each URI in order to set specific properties on Beans.
  */
 public class URISupport {
 
+    /**
+     * A composite URI can be split into one or more CompositeData object which each represent
the
+     * individual URIs that comprise the composite one.
+     */
     public static class CompositeData {
         private String host;
         private String scheme;
@@ -100,6 +107,15 @@ public class URISupport {
         }
     }
 
+    /**
+     * Give a URI break off any URI options and store them in a Key / Value Mapping.
+     *
+     * @param uri
+     * 		The URI whose query should be extracted and processed.
+     *
+     * @return A Mapping of the URI options.
+     * @throws URISyntaxException
+     */
     public static Map<String, String> parseQuery(String uri) throws URISyntaxException
{
         try {
             uri = uri.substring(uri.lastIndexOf("?") + 1); // get only the relevant part
of the query
@@ -123,6 +139,18 @@ public class URISupport {
         }
     }
 
+    /**
+     * Given a URI parse and extract any URI query options and return them as a Key / Value
mapping.
+     *
+     * This method differs from the {@link parseQuery} method in that it handles composite
URI types and
+     * will extract the URI options from the outermost composite URI.
+     *
+     * @param uri
+     * 		The URI whose query should be extracted and processed.
+     *
+     * @return A Mapping of the URI options.
+     * @throws URISyntaxException
+     */
     public static Map<String, String> parseParameters(URI uri) throws URISyntaxException
{
         if (!isCompositeURI(uri)) {
             return uri.getQuery() == null ? emptyMap() : parseQuery(stripPrefix(uri.getQuery(),
"?"));
@@ -138,10 +166,37 @@ public class URISupport {
         }
     }
 
+    /**
+     * Given a Key / Value mapping create and append a URI query value that represents the
mapped entries, return the
+     * newly updated URI that contains the value of the given URI and the appended query
value.
+     *
+     * @param uri
+     * 		The source URI that will have the Map entries appended as a URI query value.
+     * @param queryParameters
+     * 		The Key / Value mapping that will be transformed into a URI query string.
+     *
+     * @return A new URI value that combines the given URI and the constructed query string.
+     * @throws URISyntaxException
+     */
     public static URI applyParameters(URI uri, Map<String, String> queryParameters)
throws URISyntaxException {
         return applyParameters(uri, queryParameters, "");
     }
 
+    /**
+     * Given a Key / Value mapping create and append a URI query value that represents the
mapped entries, return the
+     * newly updated URI that contains the value of the given URI and the appended query
value.  Each entry in the query
+     * string is prefixed by the supplied optionPrefix string.
+     *
+     * @param uri
+     * 		The source URI that will have the Map entries appended as a URI query value.
+     * @param queryParameters
+     * 		The Key / Value mapping that will be transformed into a URI query string.
+     * @param optionPrefix
+     * 		A string value that when not null or empty is used to prefix each query option key.
+     *
+     * @return A new URI value that combines the given URI and the constructed query string.
+     * @throws URISyntaxException
+     */
     public static URI applyParameters(URI uri, Map<String, String> queryParameters,
String optionPrefix) throws URISyntaxException {
         if (queryParameters != null && !queryParameters.isEmpty()) {
             StringBuffer newQuery = uri.getRawQuery() != null ? new StringBuffer(uri.getRawQuery())
: new StringBuffer() ;
@@ -165,14 +220,28 @@ public class URISupport {
     }
 
     /**
-     * Removes any URI query from the given uri
+     * Removes any URI query from the given uri and return a new URI that does not contain
the query portion.
+     *
+     * @param uri
+     * 		The URI whose query value is to be removed.
+     *
+     * @return a new URI that does not contain a query value.
+     * @throws URISyntaxException
      */
     public static URI removeQuery(URI uri) throws URISyntaxException {
         return createURIWithQuery(uri, null);
     }
 
     /**
-     * Creates a URI with the given query
+     * Creates a URI with the given query, removing an previous query value from the given
URI.
+     *
+     * @param uri
+     * 		The source URI whose existing query is replaced with the newly supplied one.
+     * @param query
+     * 		The new URI query string that should be appended to the given URI.
+     *
+     * @return a new URI that is a combination of the original URI and the given query string.
+     * @throws URISyntaxException
      */
     public static URI createURIWithQuery(URI uri, String query) throws URISyntaxException
{
         String schemeSpecificPart = uri.getRawSchemeSpecificPart();
@@ -191,19 +260,36 @@ public class URISupport {
         return new URI(uri.getScheme(), schemeSpecificPart, uri.getFragment());
     }
 
+    /**
+     * Given a composite URI, parse the individual URI elements contained within that URI
and return
+     * a CompsoteData instance that contains the parsed URI values.
+     *
+     * @param uri
+     * 		The target URI that should be parsed.
+     *
+     * @return a new CompsiteData instance representing the parsed composite URI.
+     * @throws URISyntaxException
+     */
     public static CompositeData parseComposite(URI uri) throws URISyntaxException {
 
         CompositeData rc = new CompositeData();
         rc.scheme = uri.getScheme();
         String ssp = stripPrefix(uri.getRawSchemeSpecificPart().trim(), "//").trim();
 
-
         parseComposite(uri, rc, ssp);
 
         rc.fragment = uri.getFragment();
         return rc;
     }
 
+    /**
+     * Examine a URI and determine if it is a Composite type or not.
+     *
+     * @param uri
+     * 		The URI that is to be examined.
+     *
+     * @return true if the given URI is a Compsote type.
+     */
     public static boolean isCompositeURI(URI uri) {
         String ssp = stripPrefix(uri.getRawSchemeSpecificPart().trim(), "//").trim();
 
@@ -213,6 +299,17 @@ public class URISupport {
         return false;
     }
 
+    /**
+     * Given a string and a position in that string of an open parend, find the matching
close parend.
+     *
+     * @param str
+     * 		The string to be searched for a matching parend.
+     * @param first
+     * 		The index in the string of the opening parend whose close value is to be searched.
+     *
+     * @return the index in the string where the closing parend is located.
+     * @throws URISyntaxException fi the string does not contain a matching parend.
+     */
     public static int indexOfParenthesisMatch(String str, int first) throws URISyntaxException
{
         int index = -1;
 
@@ -245,9 +342,17 @@ public class URISupport {
     }
 
     /**
+     * Given a composite URI and a CompositeData instance and the scheme specific part extracted
from the source URI,
+     * parse the composite URI and populate the CompositeData object with the results.  The
source URI is used only
+     * for logging as the ssp should have already been extracted from it and passed here.
+     *
      * @param uri
+     * 		The original source URI whose ssp is parsed into the composite data.
      * @param rc
+     * 		The CompsositeData instance that will be populated from the given ssp.
      * @param ssp
+     * 		The scheme specific part from the original string that is a composite or one or
more URIs.
+     *
      * @throws URISyntaxException
      */
     private static void parseComposite(URI uri, CompositeData rc, String ssp) throws URISyntaxException
{
@@ -300,8 +405,13 @@ public class URISupport {
     }
 
     /**
+     * Given the inner portion of a composite URI, split and return each inner URI as a string
+     * element in a new String array.
+     *
      * @param str
-     * @return
+     * 		The inner URI elements of a composite URI string.
+     *
+     * @return an array containing each inner URI from the composite one.
      */
     private static String[] splitComponents(String str) {
         List<String> l = new ArrayList<String>();
@@ -338,6 +448,16 @@ public class URISupport {
         return rc;
     }
 
+    /**
+     * String the given prefix from the target string and return the result.
+     *
+     * @param value
+     * 		The string that should be trimmed of the given prefix if present.
+     * @param prefix
+     * 		The prefix to remove from the target string.
+     *
+     * @return either the original string or a new string minus the supplied prefix if present.
+     */
     public static String stripPrefix(String value, String prefix) {
         if (value.startsWith(prefix)) {
             return value.substring(prefix.length());
@@ -345,10 +465,29 @@ public class URISupport {
         return value;
     }
 
+    /**
+     * Strip a URI of its scheme element.
+     *
+     * @param uri
+     * 		The URI whose scheme value should be stripped.
+     *
+     * @return The stripped URI value.
+     * @throws URISyntaxException
+     */
     public static URI stripScheme(URI uri) throws URISyntaxException {
         return new URI(stripPrefix(uri.getSchemeSpecificPart().trim(), "//"));
     }
 
+    /**
+     * Given a key / value mapping, create and return a URI formatted query string that is
valid and
+     * can be appended to a URI.
+     *
+     * @param options
+     * 		The Mapping that will create the new Query string.
+     *
+     * @return a URI formatted query string.
+     * @throws URISyntaxException
+     */
     public static String createQueryString(Map<String, String> options) throws URISyntaxException
{
         try {
             if (options.size() > 0) {
@@ -375,8 +514,19 @@ public class URISupport {
     }
 
     /**
-     * Creates a URI from the original URI and the remaining paramaters
+     * Creates a URI from the original URI and the remaining parameters.
+     *
+     * When the query options of a URI are applied to certain objects the used portion of
the query options needs
+     * to be removed and replaced with those that remain so that other parts of the code
can attempt to apply the
+     * remainder or give an error is unknown values were given.  This method is used to update
a URI with those
+     * remainder values.
      *
+     * @param originalURI
+     *		The URI whose current parameters are remove and replaced with the given remainder
value.
+     * @param params
+     * 		The URI params that should be used to replace the current ones in the target.
+     *
+     * @return a new URI that matches the original one but has its query options replaced
with the given ones.
      * @throws URISyntaxException
      */
     public static URI createRemainingURI(URI originalURI, Map<String, String> params)
throws URISyntaxException {
@@ -387,12 +537,31 @@ public class URISupport {
         return createURIWithQuery(originalURI, s);
     }
 
+    /**
+     * Given a URI value create and return a new URI that matches the target one but with
the scheme value
+     * supplied to this method.
+     *
+     * @param bindAddr
+     * 		The URI whose scheme value should be altered.
+     * @param scheme
+     * 		The new scheme value to use for the returned URI.
+     *
+     * @return a new URI that is a copy of the original except that its scheme matches the
supplied one.
+     * @throws URISyntaxException
+     */
     public static URI changeScheme(URI bindAddr, String scheme) throws URISyntaxException
{
         return new URI(scheme, bindAddr.getUserInfo(), bindAddr.getHost(), bindAddr.getPort(),
bindAddr
             .getPath(), bindAddr.getQuery(), bindAddr.getFragment());
     }
 
-
+    /**
+     * Examine the supplied string and ensure that all parends appear as matching pairs.
+     *
+     * @param str
+     * 		The target string to examine.
+     *
+     * @return true if the target string has valid parend pairings.
+     */
     public static boolean checkParenthesis(String str) {
         boolean result = true;
         if (str != null) {



Mime
View raw message