From de7617e9c782728063b8671dbe67af096c4f0e9d Mon Sep 17 00:00:00 2001 From: "Timothy A. Bish" Date: Fri, 21 Sep 2012 03:31:13 +0000 Subject: [PATCH] fix for: https://issues.apache.org/jira/browse/AMQ-730 Update some JavaDocs git-svn-id: https://svn.apache.org/repos/asf/activemq/trunk@1388313 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/activemq/ActiveMQConnection.java | 8 +- .../activemq/ActiveMQConnectionFactory.java | 8 +- .../org/apache/activemq/util/URISupport.java | 181 +++++++++++++++++- 3 files changed, 183 insertions(+), 14 deletions(-) diff --git a/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnection.java b/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnection.java index 66b1560563..8fd3b4c427 100755 --- a/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnection.java +++ b/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnection.java @@ -1690,10 +1690,10 @@ public class ActiveMQConnection implements Connection, TopicConnection, QueueCon } /** - * 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; diff --git a/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnectionFactory.java b/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnectionFactory.java index 343a67f0b9..3d8844bf34 100755 --- a/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnectionFactory.java +++ b/activemq-core/src/main/java/org/apache/activemq/ActiveMQConnectionFactory.java @@ -830,10 +830,10 @@ public class ActiveMQConnectionFactory extends JNDIBaseStorable implements Conne } /** - * 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; diff --git a/activemq-core/src/main/java/org/apache/activemq/util/URISupport.java b/activemq-core/src/main/java/org/apache/activemq/util/URISupport.java index 596b4dca1e..765be8648d 100755 --- a/activemq-core/src/main/java/org/apache/activemq/util/URISupport.java +++ b/activemq-core/src/main/java/org/apache/activemq/util/URISupport.java @@ -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 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 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 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 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 l = new ArrayList(); @@ -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 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 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) {