You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by cb...@apache.org on 2018/10/01 16:09:11 UTC
svn commit: r1842514 [2/2] - in /velocity/tools/trunk: ./
velocity-tools-generic/src/main/java/org/apache/velocity/tools/
velocity-tools-generic/src/main/java/org/apache/velocity/tools/config/
velocity-tools-generic/src/main/java/org/apache/velocity/to...
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LinkTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LinkTool.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LinkTool.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LinkTool.java Mon Oct 1 16:09:11 2018
@@ -221,6 +221,7 @@ public class LinkTool extends SafeConfig
* Equivalent to clone, but with no checked exceptions.
* If for some unfathomable reason clone() doesn't work,
* this will throw a RuntimeException.
+ * @return new LinkTool
*/
protected LinkTool duplicate()
{
@@ -232,6 +233,8 @@ public class LinkTool extends SafeConfig
* If for some unfathomable reason clone() doesn't work,
* this will throw a RuntimeException. If doing a deep
* clone, then the parameter Map will also be cloned.
+ * @param deep whether to make a deep copy
+ * @return new LinkTool
*/
protected LinkTool duplicate(boolean deep)
{
@@ -278,6 +281,7 @@ public class LinkTool extends SafeConfig
* Sets whether or not the {@link #setParam} method
* will override existing query values for the same key or simply append
* the new value to a list of existing values.
+ * @param addParams whether to add or replace params
*/
public void setAppendParams(boolean addParams)
{
@@ -291,6 +295,7 @@ public class LinkTool extends SafeConfig
* one. NOTE: using {@link #absolute()}, {@link #absolute(Object)},
* {@link #relative()}, or {@link #relative(Object)} will alter this
* setting accordingly on the new instances they return.
+ * @param forceRelative whether to force a relative URI
*/
public void setForceRelative(boolean forceRelative)
{
@@ -300,6 +305,7 @@ public class LinkTool extends SafeConfig
/**
* This will treat empty strings like null values
* and will trim any trailing ':' character.
+ * @param obj scheme
*/
public void setScheme(Object obj)
{
@@ -321,11 +327,19 @@ public class LinkTool extends SafeConfig
}
}
+ /**
+ * Sets user info
+ * @param obj user info
+ */
public void setUserInfo(Object obj)
{
this.user = obj == null ? null : String.valueOf(obj);
}
+ /**
+ Sets host
+ @param obj host
+ */
public void setHost(Object obj)
{
this.host = obj == null ? null : String.valueOf(obj);
@@ -335,6 +349,7 @@ public class LinkTool extends SafeConfig
* If the specified object is null, this will set the port value
* to -1 to indicate that. If it is non-null and cannot be converted
* to an integer, then it will be set to -2 to indicate an error.
+ * @param obj port
*/
public void setPort(Object obj)
{
@@ -364,6 +379,7 @@ public class LinkTool extends SafeConfig
* If this instance is not opaque and the specified value does
* not start with a '/' character, then that will be prepended
* automatically.
+ * @param obj path
*/
public void setPath(Object obj)
{
@@ -386,6 +402,7 @@ public class LinkTool extends SafeConfig
* to the current {@link #getPath} value. If the specified
* value is null or this instance is opaque, then this is
* a no-op.
+ * @param obj path
*/
public void appendPath(Object obj)
{
@@ -400,6 +417,9 @@ public class LinkTool extends SafeConfig
* If neither is null, this will append the end to the start,
* making sure that there is only one '/' character between
* the two values.
+ * @param start start path
+ * @param end end path
+ * @return combined path
*/
protected String combinePath(String start, String end)
{
@@ -435,6 +455,7 @@ public class LinkTool extends SafeConfig
* replace any current query value with that. If it is a String,
* it will use {@link #parseQuery(String)} to parse it into a map
* of keys to values.
+ * @param obj query
*/
public void setQuery(Object obj)
{
@@ -481,6 +502,10 @@ public class LinkTool extends SafeConfig
}
}
+ /**
+ * @param qs query string
+ * @return normalized string
+ */
protected String normalizeQuery(String qs)
{
// if we have multiple pairs...
@@ -495,6 +520,8 @@ public class LinkTool extends SafeConfig
/**
* Converts the map of keys to values into a query string.
+ * @param parameters parameters
+ * @return query string
*/
public String toQuery(Map parameters)
{
@@ -519,6 +546,7 @@ public class LinkTool extends SafeConfig
/**
* Uses {@link #combineQuery} to append the specified value
* to the current {@link #getQuery} value.
+ * @param obj query to append
*/
public void appendQuery(Object obj)
{
@@ -536,6 +564,9 @@ public class LinkTool extends SafeConfig
* already under that key. If {@link #appendParams} is
* false, this will override the existing values with the
* specified new value.
+ * @param key parameter key
+ * @param value parameter value
+ * @param append whether to append parameter to existing ones with same key
*/
public void setParam(Object key, Object value, boolean append)
{
@@ -621,6 +652,8 @@ public class LinkTool extends SafeConfig
* is not a Map, it will turn it into a String and use {@link #parseQuery} to
* parse it. Once it is a Map, it will iterate through the entries appending
* each key/value to the current query data.
+ * @param obj parameters
+ * @param append whether to append parameters
*/
public void setParams(Object obj, boolean append)
{
@@ -653,6 +686,8 @@ public class LinkTool extends SafeConfig
/**
* Removes the query pair(s) with the specified key from the
* query data and returns the remove value(s), if any.
+ * @param key parameter key
+ * @return parameter value or null
*/
public Object removeParam(Object key)
{
@@ -667,6 +702,7 @@ public class LinkTool extends SafeConfig
/**
* In this class, this method ignores true values. If passed a false value,
* it will call {@link #setQuery} with a null value to clear all query data.
+ * @param keep <code>false</code> will clear query
*/
protected void handleParamsBoolean(boolean keep)
{
@@ -682,6 +718,9 @@ public class LinkTool extends SafeConfig
* at the start of the second param and any '&' or '&amp;' at the
* end of the first one, then combine the two, making sure that they
* are separated by only one delimiter.
+ * @param current current query
+ * @param add added query
+ * @return combined query
*/
protected String combineQuery(String current, String add)
{
@@ -722,6 +761,9 @@ public class LinkTool extends SafeConfig
* query pair string. If the value is an array or List, then
* this will create a delimited string of query pairs, reusing
* the same key for each of the values separately.
+ * @param key parameter key
+ * @param value parameter value(s)
+ * @return encoded query string fragment
*/
protected String toQuery(Object key, Object value)
{
@@ -773,6 +815,8 @@ public class LinkTool extends SafeConfig
* specified query string match the current query delimiter
* and then uses {@link #parseQuery(String,String)} to parse it
* according to that same delimiter.
+ * @param query query string
+ * @return parameters map
*/
protected Map<String,Object> parseQuery(String query)
{
@@ -785,6 +829,9 @@ public class LinkTool extends SafeConfig
* If there are multiple query pairs in the string that have the same
* key, then the values will be combined into a single List value
* associated with that key.
+ * @param query query string
+ * @param queryDelim query delimiter
+ * @return parameters map
*/
protected Map<String,Object> parseQuery(String query, String queryDelim)
{
@@ -826,6 +873,7 @@ public class LinkTool extends SafeConfig
/**
* Sets the anchor for this instance and treats empty strings like null.
+ * @param obj fragment
*/
public void setFragment(Object obj)
{
@@ -851,6 +899,8 @@ public class LinkTool extends SafeConfig
* values from the URI object to this instance, when not null or empty.
* In other words, when given a URI this will only set values present
* in the URI.
+ * @param obj URI
+ * @return success
*/
protected boolean setFromURI(Object obj)
{
@@ -922,6 +972,8 @@ public class LinkTool extends SafeConfig
/**
* Turns the specified object into a string and thereby a URI.
+ * @param obj source object
+ * @return URI or null
*/
protected URI toURI(Object obj)
{
@@ -947,6 +999,7 @@ public class LinkTool extends SafeConfig
* Tries to create a URI from the current port, opacity, scheme,
* userInfo, host, path, query and fragment set for this instance,
* using the {@link URI} constructor that is appropriate to the opacity.
+ * @return URI object or null
*/
protected URI createURI()
{
@@ -996,6 +1049,7 @@ public class LinkTool extends SafeConfig
/**
* Returns the configured charset used by the {@link #encode} and
* {@link #decode} methods.
+ * @return character encoding
*/
public String getCharacterEncoding()
{
@@ -1006,6 +1060,7 @@ public class LinkTool extends SafeConfig
* Returns true if the query delimiter used by this instance is
* using <code>&amp;</code> as the delimiter for query data pairs
* or just using <code>&</code>.
+ * @return whether the query string delimiter uses the XHTML delimiter
*/
public boolean isXHTML()
{
@@ -1015,6 +1070,7 @@ public class LinkTool extends SafeConfig
/**
* Returns true if {@link #param(Object,Object)} appends values;
* false if the method overwrites existing value(s) for the specified key.
+ * @return whether parameters are appended to the query string
*/
public boolean getAppendParams()
{
@@ -1024,6 +1080,8 @@ public class LinkTool extends SafeConfig
/**
* Returns a new instance with the specified value set as its scheme.
+ * @param scheme scheme
+ * @return new LinkTool
*/
public LinkTool scheme(Object scheme)
{
@@ -1034,6 +1092,7 @@ public class LinkTool extends SafeConfig
/**
* Returns a new instance with the scheme set to "https".
+ * @return new LinkTool
*/
public LinkTool secure()
{
@@ -1042,6 +1101,7 @@ public class LinkTool extends SafeConfig
/**
* Returns a new instance with the scheme set to "http".
+ * @return new LinkTool
*/
public LinkTool insecure()
{
@@ -1050,6 +1110,7 @@ public class LinkTool extends SafeConfig
/**
* Return the scheme value for this instance.
+ * @return scheme
*/
public String getScheme()
{
@@ -1058,6 +1119,7 @@ public class LinkTool extends SafeConfig
/**
* Returns true if this instance's scheme is "https".
+ * @return whether the protocol is secure
*/
public boolean isSecure()
{
@@ -1066,6 +1128,7 @@ public class LinkTool extends SafeConfig
/**
* Returns true if this instance represents an opaque URI.
+ * @return opacity flag
* @see URI
*/
public boolean isOpaque()
@@ -1076,6 +1139,8 @@ public class LinkTool extends SafeConfig
/**
* Returns a new instance with the specified value
* set as its user info.
+ * @param info user info
+ * @return new LinkTool
*/
public LinkTool user(Object info)
{
@@ -1086,6 +1151,7 @@ public class LinkTool extends SafeConfig
/**
* Returns the {@link URI#getUserInfo()} value for this instance.
+ * @return user info
*/
public String getUser()
{
@@ -1096,6 +1162,8 @@ public class LinkTool extends SafeConfig
* Returns a new instance with the specified value set as its
* host. If no scheme has yet been set, the new instance will
* also have its scheme set to the {@link #DEFAULT_SCHEME} (http).
+ * @param host host
+ * @return new LinkTool
*/
public LinkTool host(Object host)
{
@@ -1112,6 +1180,7 @@ public class LinkTool extends SafeConfig
/**
* Return the host value for this instance.
+ * @return host
*/
public String getHost()
{
@@ -1125,6 +1194,8 @@ public class LinkTool extends SafeConfig
* null for {@link #toString} and other
* {@link #createURI}-dependent methods to alert the user
* to the error.
+ * @param port port
+ * @return new LinkTool
*/
public LinkTool port(Object port)
{
@@ -1135,6 +1206,7 @@ public class LinkTool extends SafeConfig
/**
* Returns the port value, if any.
+ * @return port or null
*/
public Integer getPort()
{
@@ -1148,6 +1220,8 @@ public class LinkTool extends SafeConfig
/**
* Returns a new instance with the specified value
* set as its path.
+ * @param pth path
+ * @return new link tool
*/
public LinkTool path(Object pth)
{
@@ -1158,6 +1232,7 @@ public class LinkTool extends SafeConfig
/**
* Returns the current path value for this instance.
+ * @return path
*/
public String getPath()
{
@@ -1167,6 +1242,8 @@ public class LinkTool extends SafeConfig
/**
* Appends the given value to the end of the current
* path value.
+ * @param pth path to append
+ * @return new LinkTool
*/
public LinkTool append(Object pth)
{
@@ -1179,6 +1256,7 @@ public class LinkTool extends SafeConfig
* Returns the directory stack
* in the set {@link #getPath()} value, by just trimming
* off all that follows the last "/".
+ * @return directory stack
*/
public String getDirectory()
{
@@ -1197,6 +1275,7 @@ public class LinkTool extends SafeConfig
/**
* Returns the last section of the path,
* which is all that follows the final "/".
+ * @return file
*/
public String getFile()
{
@@ -1220,6 +1299,7 @@ public class LinkTool extends SafeConfig
* was an error when the port value was last set. It will
* return null for any opaque URLs as well, as those have
* no host or port.
+ * @return root
*/
public String getRoot()
{
@@ -1238,6 +1318,7 @@ public class LinkTool extends SafeConfig
* sets the path, query, and fragment to null on
* the returned instance.
* @see #getRoot()
+ * @return new LinkTool
*/
public LinkTool root()
{
@@ -1256,6 +1337,7 @@ public class LinkTool extends SafeConfig
* Returns a new LinkTool instance with
* the path set to the result of {@link #getDirectory()}
* and the query and fragment set to null.
+ * @return new LinkTool
*/
public LinkTool directory()
{
@@ -1274,6 +1356,7 @@ public class LinkTool extends SafeConfig
/**
* Returns true if this instance is being forced to
* return relative URIs or has a null scheme value.
+ * @return whether the link is relative
*/
public boolean isRelative()
{
@@ -1283,6 +1366,7 @@ public class LinkTool extends SafeConfig
/**
* Returns a copy of this LinkTool instance that has
* {@link #setForceRelative} set to true.
+ * @return new LinkTool
*/
public LinkTool relative()
{
@@ -1330,6 +1414,7 @@ public class LinkTool extends SafeConfig
* At this level, this only returns the result of {@link #getDirectory}.
* It is here as an extension hook for subclasses to change the
* "context" for relative links.
+ * @return context path
* @see #relative(Object)
* @see #getDirectory
*/
@@ -1341,6 +1426,7 @@ public class LinkTool extends SafeConfig
/**
* Returns true if this instance has a scheme value
* and is not being forced to create relative URIs.
+ * @return whether this link is absolute
*/
public boolean isAbsolute()
{
@@ -1351,6 +1437,7 @@ public class LinkTool extends SafeConfig
* Returns a copy of this LinkTool instance that has
* {@link #setForceRelative} set to false and sets the
* scheme to the "http" if no scheme has been set yet.
+ * @return new LinkTool
*/
public LinkTool absolute()
{
@@ -1437,6 +1524,7 @@ public class LinkTool extends SafeConfig
* If the tool is not in "safe mode"--which it is by default--
* this will return the {@link URI} representation of this instance,
* if any.
+ * @return URI
* @see SafeConfig#isSafeMode()
*/
public URI getUri()
@@ -1455,6 +1543,7 @@ public class LinkTool extends SafeConfig
* or query data set for this LinkTool. A typical application of
* this method is with the HTML base tag. For example:
* <code><base href="$link.baseRef"></code>
+ * @return base link
*/
public String getBaseRef()
{
@@ -1468,6 +1557,8 @@ public class LinkTool extends SafeConfig
* Sets the specified value as the current query data,
* after normalizing the pair delimiters. This overrides
* any existing query.
+ * @param query query string
+ * @return new LinkTool
*/
public LinkTool query(Object query)
{
@@ -1478,6 +1569,7 @@ public class LinkTool extends SafeConfig
/**
* Returns the current query as a string, if any.
+ * @return query string
*/
public String getQuery()
{
@@ -1615,12 +1707,16 @@ public class LinkTool extends SafeConfig
/**
* Returns the anchor (internal document reference) set for this link.
+ * @return anchor
*/
public String getAnchor()
{
return this.fragment;
}
+ /**
+ * @return self
+ */
public LinkTool getSelf()
{
// there are no self-params to bother with at this level,
@@ -1634,6 +1730,7 @@ public class LinkTool extends SafeConfig
* Typically, it is not necessary to call this method explicitely.
* Velocity will call the toString() method automatically to obtain
* a representable version of an object.
+ * @return string representation
*/
public String toString()
{
@@ -1657,6 +1754,8 @@ public class LinkTool extends SafeConfig
* but then URI encodes all the % from that encoding. Here,
* we isolate the query data and manually decode the encoded
* %25 in that section back to %, without decoding anything else.
+ * @param url source url
+ * @return decoded url
*/
protected String decodeQueryPercents(String url)
{
@@ -1727,6 +1826,8 @@ public class LinkTool extends SafeConfig
* LinkTool instance whose toString() method returns a
* String equal to that returned by this instance's toString()
* @see #toString()
+ * @param obj object to compare to
+ * @return equality
*/
@Override
public boolean equals(Object obj)
@@ -1748,6 +1849,7 @@ public class LinkTool extends SafeConfig
* Returns the hash code for the result of toString().
* If toString() returns {@code null} (yes, we do break that contract),
* this will return {@code -1}.
+ * @return hash code
*/
@Override
public int hashCode()
@@ -1764,7 +1866,7 @@ public class LinkTool extends SafeConfig
/**
* Delegates encoding of the specified url content to
* {@link URLEncoder#encode} using the configured character encoding.
- *
+ * @param obj URL to encode
* @return String - the encoded url.
*/
public String encode(Object obj)
@@ -1787,7 +1889,7 @@ public class LinkTool extends SafeConfig
/**
* Delegates decoding of the specified url content to
* {@link URLDecoder#decode} using the configured character encoding.
- *
+ * @param obj URL to decode
* @return String - the decoded url.
*/
public String decode(Object obj)
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LocaleConfig.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LocaleConfig.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LocaleConfig.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LocaleConfig.java Mon Oct 1 16:09:11 2018
@@ -67,6 +67,7 @@ public class LocaleConfig extends SafeCo
/**
* Sets the default locale for this instance.
+ * @param locale default locale to use
*/
protected void setLocale(Locale locale)
{
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LoopTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LoopTool.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LoopTool.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/LoopTool.java Mon Oct 1 16:09:11 2018
@@ -135,6 +135,9 @@ public class LoopTool extends SafeConfig
* watched. If the given name is {@code null}, then this will return
* {@code null} even if the object can be watched. Provided names cannot
* be {@code null}.
+ * @param obj an object that Velocity's #foreach directive can iterate over
+ * @param name loop name
+ * @return a {@link ManagedIterator} that this tool instance will track
* @see #watch(Object)
*/
public ManagedIterator watch(Object obj, String name)
@@ -187,6 +190,7 @@ public class LoopTool extends SafeConfig
* This is just like {@link #stop()} except that the stop command is issued
* <strong>only</strong> to the loop/iterator with the specified name.
* If no such loop is found with that name, then no stop command is issued.
+ * @param name loop name
* @see #stop()
*/
public void stop(String name)
@@ -207,6 +211,7 @@ public class LoopTool extends SafeConfig
* both to the loop/iterator with the specified name and all loops nested within
* it. If no such loop is found with that name, then no stop commands are
* issued.
+ * @param name loop name
* @see #stop()
* @see #stop(String)
*/
@@ -267,6 +272,7 @@ public class LoopTool extends SafeConfig
* provided by the likes of {@link ManagedIterator#exclude(Object)}, any elements
* skipped are still considered in the results returned by {@link #getCount()}
* and {@link #isFirst()}.
+ * @param number number of iterations
*/
public void skip(int number)
{
@@ -281,6 +287,8 @@ public class LoopTool extends SafeConfig
/**
* This tells the specified loop to skip ahead the specified number of
* iterations.
+ * @param number number of iterations
+ * @param name loop name
* @see #skip(int)
*/
public void skip(int number, String name)
@@ -310,7 +318,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns {@code true} if the current loop is on its first iteration.
+ * @return {@code true} if the current loop is on its first iteration.
*/
public Boolean isFirst()
{
@@ -322,8 +330,9 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns {@code true} if the loop with the specified name
+ * @return {@code true} if the loop with the specified name
* is on its first iteration.
+ * @param name loop name
*/
public Boolean isFirst(String name)
{
@@ -337,7 +346,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the result of {@link #isFirst}. Exists to allow $loop.first syntax.
+ * @return the result of {@link #isFirst}. Exists to allow $loop.first syntax.
*/
public Boolean getFirst()
{
@@ -345,7 +354,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns {@code true} if the current loop is on its last iteration.
+ * @return {@code true} if the current loop is on its last iteration.
*/
public Boolean isLast()
{
@@ -357,8 +366,9 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns {@code true} if the loop with the specified name
+ * @return {@code true} if the loop with the specified name
* is on its last iteration.
+ * @param name loop name
*/
public Boolean isLast(String name)
{
@@ -372,7 +382,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the result of {@link #isLast}. Exists to allow $loop.last syntax.
+ * @return the result of {@link #isLast}. Exists to allow $loop.last syntax.
*/
public Boolean getLast()
{
@@ -393,6 +403,8 @@ public class LoopTool extends SafeConfig
* This syntax is shorter and clearer than {@code $loop.getCount('foo')}.
* If the key starts with a property name and ends with an outer loop
* name, then the value of that property for that loop is returned.
+ * @param key sync'ed Iterator name
+ * @return current iterator value
*/
public Object get(String key)
{
@@ -442,6 +454,9 @@ public class LoopTool extends SafeConfig
/**
* Asks the loop with the specified name for the current value
* of the specified sync'ed iterator, if any.
+ * @param name loop name
+ * @param synced sync'ed Iterator name
+ * @return current iterator value
*/
public Object get(String name, String synced)
{
@@ -460,6 +475,7 @@ public class LoopTool extends SafeConfig
* you {@link #skip} ahead in this loop, those skipped iterations will
* still be reflected in the index. If iteration has not begun, this
* will return {@code null}.
+ * @return current loop index
*/
public Integer getIndex()
{
@@ -477,6 +493,8 @@ public class LoopTool extends SafeConfig
* you {@link #skip} ahead in this loop, those skipped iterations will
* still be reflected in the index. If iteration has not begun, this
* will return {@code null}.
+ * @param name loop name
+ * @return current loop index
*/
public Integer getIndex(String name)
{
@@ -493,6 +511,7 @@ public class LoopTool extends SafeConfig
* is the first iteration, then the count will be 1. If you {@link #skip}
* ahead in this loop, those skipped iterations will still be included in
* the count.
+ * @return items count
*/
public Integer getCount()
{
@@ -508,6 +527,8 @@ public class LoopTool extends SafeConfig
* is the first iteration, then the count will be 1. If you {@link #skip}
* ahead in this loop, those skipped iterations will still be included in
* the count.
+ * @param name loop name
+ * @return loop items count
*/
public Integer getCount(String name)
{
@@ -526,6 +547,7 @@ public class LoopTool extends SafeConfig
* isFirst, isLast, etc which would otherwise fail on the last item
* in a loop due to the necessity of popping iterators off the
* stack when the last item is retrieved. (See VELTOOLS-124)
+ * @return most recent iterator
*/
public ManagedIterator getThis()
{
@@ -537,6 +559,7 @@ public class LoopTool extends SafeConfig
* This is only useful for debugging, as iterators are
* popped off the stack at the start of their final iteration,
* making this frequently "incorrect".
+ * @return depth
*/
public int getDepth()
{
@@ -547,6 +570,8 @@ public class LoopTool extends SafeConfig
/**
* Finds the {@link ManagedIterator} with the specified name
* if it is in this instance's iterator stack.
+ * @param name loop name
+ * @return loop iterator
*/
protected ManagedIterator findIterator(String name)
{
@@ -564,6 +589,7 @@ public class LoopTool extends SafeConfig
/**
* Don't let templates call this, but allow subclasses
* and ManagedIterator to have access.
+ * @return pop'ed iterator
*/
protected ManagedIterator pop()
{
@@ -578,6 +604,8 @@ public class LoopTool extends SafeConfig
* nice little try/catch block to prevent exceptions from
* escaping into the template. In the case of such problems,
* this will return {@code null}.
+ * @param obj target iterator
+ * @return wrapped iterator or null
*/
protected Iterator getIterator(Object obj)
{
@@ -632,7 +660,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the name of this instance.
+ * @return the name of this instance.
*/
public String getName()
{
@@ -640,7 +668,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns true if either 0 or 1 elements have been returned
+ * @return true if either 0 or 1 elements have been returned
* by {@link #next()}.
*/
public boolean isFirst()
@@ -653,7 +681,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns true if the last element returned by {@link #next()}
+ * @return true if the last element returned by {@link #next()}
* is the last element available in the iterator being managed
* which satisfies any/all {@link ActionCondition}s set for this
* instance. Otherwise, returns false.
@@ -664,7 +692,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the result of {@link #isFirst}. Exists to allow $loop.this.first syntax.
+ * @return the result of {@link #isFirst}. Exists to allow $loop.this.first syntax.
*/
public boolean getFirst()
{
@@ -672,7 +700,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the result of {@link #isLast}. Exists to allow $loop.this.last syntax.
+ * @return the result of {@link #isLast}. Exists to allow $loop.this.last syntax.
*/
public boolean getLast()
{
@@ -680,7 +708,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns true if there are more elements in the iterator
+ * @return true if there are more elements in the iterator
* being managed by this instance which satisfy all the
* {@link ActionCondition}s set for this instance. Returns
* false if there are no more valid elements available.
@@ -691,7 +719,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the result of {@link #hasNext}. Exists to allow $loop.this.hasNext syntax.
+ * @return the result of {@link #hasNext}. Exists to allow $loop.this.hasNext syntax.
*/
public boolean getHasNext()
{
@@ -770,7 +798,8 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns {@code true} if this ManagedIterator has a sync'ed
+ * @param name syn'ed iterator name
+ * @return {@code true} if this ManagedIterator has a sync'ed
* iterator with the specified name.
*/
public boolean isSyncedWith(String name)
@@ -783,9 +812,11 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the parallel value from the specified sync'ed iterator.
+ * @return the parallel value from the specified sync'ed iterator.
* If no sync'ed iterator exists with that name or that iterator
* is finished, this will return {@code null}.
+ * @param iterator name
+ * @return iterator current value
*/
public Object get(String name)
{
@@ -802,7 +833,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the number of elements returned by {@link #next()} so far.
+ * @return the number of elements returned by {@link #next()} so far.
*/
public int getCount()
{
@@ -810,7 +841,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the 0-based index of the current item.
+ * @return the 0-based index of the current item.
*/
public int getIndex()
{
@@ -818,7 +849,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the next element that meets the set {@link ActionCondition}s
+ * @return the next element that meets the set {@link ActionCondition}s
* (if any) in the iterator being managed. If there are none left, then
* this will throw a {@link NoSuchElementException}.
*/
@@ -879,6 +910,7 @@ public class LoopTool extends SafeConfig
/**
* Directs this instance to completely exclude
* any elements equal to the specified Object.
+ * @param compare value to exclude
* @return This same {@link ManagedIterator} instance
*/
public ManagedIterator exclude(Object compare)
@@ -890,6 +922,7 @@ public class LoopTool extends SafeConfig
/**
* Directs this instance to stop iterating immediately prior to
* any element equal to the specified Object.
+ * @param compare value to stop at
* @return This same {@link ManagedIterator} instance
*/
public ManagedIterator stop(Object compare)
@@ -900,6 +933,7 @@ public class LoopTool extends SafeConfig
/**
* Adds a new {@link ActionCondition} for this instance to check
* against the elements in the iterator being managed.
+ * @param condition condition
* @return This same {@link ManagedIterator} instance
*/
public ManagedIterator condition(ActionCondition condition)
@@ -928,6 +962,7 @@ public class LoopTool extends SafeConfig
* will simply replace the earlier ones under the default
* 'synced' key.</p>
*
+ * @param iterable Iterator to synchronize with
* @return This same {@link ManagedIterator} instance
* @see SyncedIterator
* @see #get(String)
@@ -944,6 +979,8 @@ public class LoopTool extends SafeConfig
* name specified here (e.g. $loop.name or $loop.get('name'))
* and are automatically updated for each iteration by this instance.
*
+ * @param iterable iterator to synchronize with
+ * @param name loop name
* @return This same {@link ManagedIterator} instance
* @see SyncedIterator
* @see #get(String)
@@ -963,6 +1000,9 @@ public class LoopTool extends SafeConfig
return this;
}
+ /**
+ * @return last sync'ed values
+ */
public Map<String,Object> getLastSyncedValues()
{
if (synced == null)
@@ -1014,6 +1054,8 @@ public class LoopTool extends SafeConfig
/**
* Returns true if the specified value meets the set {@link Condition}
+ * @param value value to test
+ * @return whether the value matchers the condition
*/
public boolean matches(Object value)
{
@@ -1120,7 +1162,7 @@ public class LoopTool extends SafeConfig
}
/**
- * Returns the currently parallel value, if any.
+ * @return the currently parallel value, if any.
*/
public Object get()
{
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/MarkupTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/MarkupTool.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/MarkupTool.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/MarkupTool.java Mon Oct 1 16:09:11 2018
@@ -74,6 +74,7 @@ public class MarkupTool extends SafeConf
/**
* Configuration
+ * @param tab tab string
*/
public void setTab(String tab)
{
@@ -398,6 +399,11 @@ public class MarkupTool extends SafeConf
/************* rendering methods **************/
+ /**
+ * Render tag
+ * @param indent indentation string
+ * @param s string builder
+ */
protected void render(String indent, StringBuilder s)
{
if (render_start(indent, s))
@@ -407,6 +413,12 @@ public class MarkupTool extends SafeConf
}
}
+ /**
+ * Start tag rendering
+ * @param indent indentation string
+ * @param s string builder
+ * @return whether a closing tag is needed
+ */
protected boolean render_start(String indent, StringBuilder s)
{
if (indent != null)
@@ -430,11 +442,19 @@ public class MarkupTool extends SafeConf
}
}
+ /**
+ * Render tag name
+ * @param s string builder
+ */
protected void render_name(StringBuilder s)
{
s.append(name == null ? "div" : name);
}
+ /**
+ * render tag id
+ * @param s string builder
+ */
protected void render_id(StringBuilder s)
{
if (id != null)
@@ -443,6 +463,10 @@ public class MarkupTool extends SafeConf
}
}
+ /**
+ * render tag classes
+ * @param s string builder
+ */
protected void render_classes(StringBuilder s)
{
if (classes != null)
@@ -460,6 +484,10 @@ public class MarkupTool extends SafeConf
}
}
+ /**
+ * Render tag attributes
+ * @param s string builder
+ */
protected void render_attributes(StringBuilder s)
{
if (attributes != null)
@@ -476,6 +504,11 @@ public class MarkupTool extends SafeConf
}
}
+ /**
+ * Render tag body
+ * @param indent indentation string
+ * @param s string builder
+ */
protected void render_body(String indent, StringBuilder s)
{
String kidIndent = indent + tool.getTab();
@@ -493,6 +526,11 @@ public class MarkupTool extends SafeConf
}
}
+ /**
+ * Render tag end
+ * @param indent indentation string
+ * @param s string builder
+ */
protected void render_end(String indent, StringBuilder s)
{
if (indent != null)
@@ -502,6 +540,9 @@ public class MarkupTool extends SafeConf
s.append("</").append(name).append('>');
}
+ /**
+ * @return string representation
+ */
public String toString()
{
StringBuilder s = new StringBuilder();
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/MathTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/MathTool.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/MathTool.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/MathTool.java Mon Oct 1 16:09:11 2018
@@ -659,6 +659,9 @@ public class MathTool extends FormatConf
// --------------------------- protected methods ------------------
/**
+ * @param in instance of wanted Number class
+ * @param out input number
+ * @return wanted Number
* @see #matchType(double,Number...)
*/
protected Number matchType(Number in, double out)
@@ -667,6 +670,10 @@ public class MathTool extends FormatConf
}
/**
+ * @param in1 instance #1 of wanted Number class
+ * @param in2 instance #1 of wanted Number class
+ * @param out input number
+ * @return wanted Number
* @see #matchType(double,Number...)
*/
protected Number matchType(Number in1, Number in2, double out)
@@ -681,6 +688,9 @@ public class MathTool extends FormatConf
* decimal when rendered) the result will be returned as a Double.
* If not and the result is < -2147483648 or > 2147483647, then a
* Long will be returned. Otherwise, an Integer will be returned.
+ * @param out target number value
+ * @param in wanted Number classes
+ * @return wanted Number
*/
protected Number matchType(double out, Number... in)
{
@@ -722,6 +732,10 @@ public class MathTool extends FormatConf
}
}
+ /**
+ * @param value target value
+ * @return wether it contains a decimal separator (non locale-aware for now - TODO)
+ */
protected boolean hasFloatingPoint(String value)
{
return value.indexOf('.') >= 0;
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/NumberTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/NumberTool.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/NumberTool.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/NumberTool.java Mon Oct 1 16:09:11 2018
@@ -81,6 +81,8 @@ public class NumberTool extends FormatCo
/**
* Convenience method equivalent to $number.format("currency", $foo).
+ * @param obj the number object to be formatted
+ * @return the specified number formatted as a currency
* @since VelocityTools 1.3
*/
public String currency(Object obj)
@@ -90,6 +92,8 @@ public class NumberTool extends FormatCo
/**
* Convenience method equivalent to $number.format("integer", $foo).
+ * @param obj the number object to be formatted
+ * @return the specified number formatted as an integer
* @since VelocityTools 1.3
*/
public String integer(Object obj)
@@ -99,6 +103,8 @@ public class NumberTool extends FormatCo
/**
* Convenience method equivalent to $number.format("number", $foo).
+ * @param obj the number object to be formatted
+ * @return the specified number formatted as a number
* @since VelocityTools 1.3
*/
public String number(Object obj)
@@ -108,6 +114,8 @@ public class NumberTool extends FormatCo
/**
* Convenience method equivalent to $number.format("percent", $foo).
+ * @param obj the number object to be formatted
+ * @return the specified number formatted as a percentage
* @since VelocityTools 1.3
*/
public String percent(Object obj)
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/RenderTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/RenderTool.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/RenderTool.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/RenderTool.java Mon Oct 1 16:09:11 2018
@@ -155,6 +155,7 @@ public class RenderTool extends SafeConf
/**
* Allow user to specify a VelocityEngine to be used
* in place of the Velocity singleton.
+ * @param ve VelocityEngine instance
*/
public void setVelocityEngine(VelocityEngine ve)
{
@@ -163,7 +164,7 @@ public class RenderTool extends SafeConf
/**
* Set the maximum number of loops allowed when recursing.
- *
+ * @param depth parse depth
* @since VelocityTools 1.2
*/
public void setParseDepth(int depth)
@@ -181,6 +182,7 @@ public class RenderTool extends SafeConf
/**
* Sets the {@link Context} to be used by the {@link #eval(String)}
* and {@link #recurse(String)} methods.
+ * @param context Velocity context
*/
public void setVelocityContext(Context context)
{
@@ -200,7 +202,7 @@ public class RenderTool extends SafeConf
/**
* Get the maximum number of loops allowed when recursing.
- *
+ * @return parse depth
* @since VelocityTools 1.2
*/
public int getParseDepth()
@@ -211,6 +213,7 @@ public class RenderTool extends SafeConf
/**
* Sets whether or not the render() and eval() methods should catch
* exceptions during their execution or not.
+ * @param catchExceptions whether to catch exceptions
* @since VelocityTools 1.3
*/
public void setCatchExceptions(boolean catchExceptions)
@@ -228,6 +231,7 @@ public class RenderTool extends SafeConf
/**
* Returns <code>true</code> if this render() and eval() methods will
* catch exceptions thrown during rendering.
+ * @return whether to catch exceptions
* @since VelocityTools 1.3
*/
public boolean getCatchExceptions()
@@ -248,6 +252,7 @@ public class RenderTool extends SafeConf
*
* @param vtl the code to be evaluated
* @return the evaluated code as a String
+ * @throws Exception if womething went wrong
*/
public String eval(String vtl) throws Exception
{
@@ -266,6 +271,7 @@ public class RenderTool extends SafeConf
* @see #eval(String)
* @param vtl the code to be evaluated
* @return the evaluated code as a String
+ * @throws Exception if womething went wrong
*/
public String recurse(String vtl) throws Exception
{
@@ -282,6 +288,7 @@ public class RenderTool extends SafeConf
* @param ctx the current Context
* @param vtl the code to be evaluated
* @return the evaluated code as a String
+ * @throws Exception if womething went wrong
*/
public String eval(Context ctx, String vtl) throws Exception
{
@@ -340,6 +347,7 @@ public class RenderTool extends SafeConf
* @param ctx the current Context
* @param vtl the code to be evaluated
* @return the evaluated code as a String
+ * @throws Exception if womething went wrong
*/
public String recurse(Context ctx, String vtl) throws Exception
{
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/ResourceTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/ResourceTool.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/ResourceTool.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/ResourceTool.java Mon Oct 1 16:09:11 2018
@@ -110,6 +110,8 @@ public class ResourceTool extends Locale
/**
* Accepts objects and uses their string value as the key.
+ * @param k key
+ * @return Key object
*/
public Key get(Object k)
{
@@ -117,11 +119,20 @@ public class ResourceTool extends Locale
return get(key);
}
+ /**
+ * Accepts objects and uses their string value as the key.
+ * @param k key
+ * @return Key object
+ */
public Key get(String key)
{
return new Key(key, this.bundles, getLocale(), null);
}
+ /**
+ * Lists available keys
+ * @return keys list
+ */
public List<String> getKeys()
{
return getKeys(null, this.bundles, getLocale());
@@ -163,6 +174,9 @@ public class ResourceTool extends Locale
* and locale, if such exists. If the baseName or locale is null
* or if the locale argument cannot be converted to a {@link Locale},
* then this will return null.
+ * @param baseName base name
+ * @param loc locale
+ * @return resource bundle
*/
protected ResourceBundle getBundle(String baseName, Object loc)
{
@@ -182,6 +196,7 @@ public class ResourceTool extends Locale
* @param key the key for the requested resource
* @param baseName the base name of the resource bundle to search
* @param loc the locale to use
+ * @return value
*/
public Object get(Object key, String baseName, Object loc)
{
@@ -209,6 +224,7 @@ public class ResourceTool extends Locale
* @param k the key for the requested resource
* @param bundles the resource bundles to search
* @param l the locale to use
+ * @return value
*/
public Object get(Object k, String[] bundles, Object l)
{
@@ -235,6 +251,7 @@ public class ResourceTool extends Locale
* @param prefix the prefix for the requested keys
* @param baseName the resource bundle base name
* @param loc the locale to use
+ * @return keys list
*/
public List<String> getKeys(String prefix, String baseName, Object loc)
{
@@ -280,6 +297,7 @@ public class ResourceTool extends Locale
* @param prefix the prefix for the requested keys
* @param bundles the resource bundles to search
* @param loc the locale to use
+ * @return keys list
* @see #getKeys(String,String,Object)
*/
public List<String> getKeys(String prefix, String[] bundles, Object loc)
@@ -306,6 +324,9 @@ public class ResourceTool extends Locale
* Renders the specified resource value and arguments as a String.
* The resource is treated as a {@link MessageFormat} pattern which
* is used for formatting along with any specified argument values.
+ * @param resource resource object
+ * @param args arguments
+ * @return formatted string
*/
public String render(Object resource, Object[] args)
{
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/ValueParser.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/ValueParser.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/ValueParser.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/ValueParser.java Mon Oct 1 16:09:11 2018
@@ -120,7 +120,7 @@ public class ValueParser extends FormatC
/**
* allow or disallow subkeys
- * @param allow
+ * @param allow flag value
*/
protected void setAllowSubkeys(boolean allow)
{
@@ -138,7 +138,7 @@ public class ValueParser extends FormatC
/**
* Set or unset read-only behaviour
- * @param ro
+ * @param ro flag value
*/
protected void setReadOnly(boolean ro)
{
@@ -149,6 +149,7 @@ public class ValueParser extends FormatC
* Sets the delimiter used for separating values in a single String value.
* The default string delimiter is a comma.
*
+ * @param stringsDelimiter strings delimiter
* @see #getValues(String)
*/
protected final void setStringsDelimiter(String stringsDelimiter)
@@ -161,6 +162,7 @@ public class ValueParser extends FormatC
* subclasses may share the same ValueParser and call configure
* at any time, while preventing templates from doing so when
* configure(Map) is locked.
+ * @param values configuration values
*/
@Override
protected void configure(ValueParser values)
@@ -225,6 +227,8 @@ public class ValueParser extends FormatC
* Returns the value mapped to the specified key
* in the {@link Map} returned by {@link #getSource()}. If there is
* no source, then this will always return {@code null}.
+ * @param key property key
+ * @return property value, or null
*/
public Object getValue(String key)
{
@@ -608,6 +612,7 @@ public class ValueParser extends FormatC
/**
* Determines whether there are subkeys available in the source map.
+ * @return <code>true</code> if there are subkeys (key names containing a dot)
*/
public boolean hasSubkeys()
{
@@ -637,6 +642,7 @@ public class ValueParser extends FormatC
/**
* returns the set of all possible first-level subkeys, including complete keys without dots (or returns keySet() if allowSubKeys is false)
+ * @return the set of all possible first-level subkeys
*/
public Set<String> getSubkeys()
{
Modified: velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/XmlTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/XmlTool.java?rev=1842514&r1=1842513&r2=1842514&view=diff
==============================================================================
--- velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/XmlTool.java (original)
+++ velocity/tools/trunk/velocity-tools-generic/src/main/java/org/apache/velocity/tools/generic/XmlTool.java Mon Oct 1 16:09:11 2018
@@ -96,7 +96,7 @@ public class XmlTool extends SafeConfig
/**
* ImportSupport initialization
- * @param config
+ * @param config configuration values
*/
protected synchronized void initializeImportSupport(ValueParser config)
{
@@ -109,7 +109,7 @@ public class XmlTool extends SafeConfig
/**
* Configuration.
- * @param values
+ * @param values configuration values
*/
protected void configure(ValueParser values)
{
@@ -164,6 +164,7 @@ public class XmlTool extends SafeConfig
/**
* Sets a singular root {@link Node} for this instance.
+ * @param node new root node
*/
protected void setRoot(Node node)
{
@@ -185,6 +186,8 @@ public class XmlTool extends SafeConfig
/**
* Parses the given XML string and uses the resulting {@link Document}
* as the root {@link Node}.
+ * @param xml XML string
+ * @return new XmlTool
*/
public XmlTool parse(String xml)
{
@@ -204,6 +207,8 @@ public class XmlTool extends SafeConfig
/**
* Reads and parses a local resource file
+ * @param resource resource path
+ * @return new XmlTool
*/
public XmlTool read(String resource)
{
@@ -240,6 +245,8 @@ public class XmlTool extends SafeConfig
/**
* Reads and parses a remote or local URL
+ * @param url resource URL
+ * @ return new XmlTool
*/
public XmlTool fetch(String url)
{
@@ -284,6 +291,8 @@ public class XmlTool extends SafeConfig
* does not contain a '/', it appends the result of {@link #getPath()}
* and a '/' to the front of it. Finally, it delegates the string to the
* {@link #find(String)} method and returns the result of that.
+ * @param o attribute name, number, xpath relative expression
+ * @return found value or null
*/
public Object get(Object o)
{
@@ -317,6 +326,7 @@ public class XmlTool extends SafeConfig
/**
* Asks {@link #get(Object)} for a "name" result.
* If none, this will return the result of {@link #getNodeName()}.
+ * @return found value or null
*/
public Object getName()
{
@@ -333,6 +343,7 @@ public class XmlTool extends SafeConfig
* Returns the name of the root node. If the internal {@link Node}
* list has more than one {@link Node}, it will only return the name
* of the first node in the list.
+ * @return node name
*/
public String getNodeName()
{
@@ -346,6 +357,7 @@ public class XmlTool extends SafeConfig
/**
* Returns the XPath that identifies the first/sole {@link Node}
* represented by this instance.
+ * @return xpath node path
*/
public String getPath()
{
@@ -362,6 +374,8 @@ public class XmlTool extends SafeConfig
* Node is an {@link Element}. If it is a non-Element node type or
* there is no value for that attribute in this element, then this
* will return {@code null}.
+ * @param o attribute name
+ * @return attribute value or null
*/
public String attr(Object o)
{
@@ -386,6 +400,7 @@ public class XmlTool extends SafeConfig
* Returns a {@link Map} of all attributes for the first/sole
* {@link Node} held internally by this instance. If that Node is
* not an {@link Element}, this will return null.
+ * @return attributes map
*/
public Map<String,String> attributes()
{
@@ -408,6 +423,7 @@ public class XmlTool extends SafeConfig
/**
* Returns {@code true} if there are no {@link Node}s internally held
* by this instance.
+ * @return whether the set of current nodes is empty
*/
public boolean isEmpty()
{
@@ -416,6 +432,7 @@ public class XmlTool extends SafeConfig
/**
* Returns the number of {@link Node}s internally held by this instance.
+ * @return the size of the set of current nodes
*/
public int size()
{
@@ -429,6 +446,7 @@ public class XmlTool extends SafeConfig
/**
* Returns an {@link Iterator} that returns new {@link XmlTool}
* instances for each {@link Node} held internally by this instance.
+ * @return an iterator on wrappers of current nodes or null
*/
public Iterator<XmlTool> iterator()
{
@@ -442,6 +460,7 @@ public class XmlTool extends SafeConfig
/**
* Returns an {@link XmlTool} that wraps only the
* first {@link Node} from this instance's internal Node list.
+ * @return a wrapper on the first node or null
*/
public XmlTool getFirst()
{
@@ -455,6 +474,7 @@ public class XmlTool extends SafeConfig
/**
* Returns an {@link XmlTool} that wraps only the
* last {@link Node} from this instance's internal Node list.
+ * @return a wrapper on the last node or null
*/
public XmlTool getLast()
{
@@ -468,6 +488,7 @@ public class XmlTool extends SafeConfig
/**
* Returns an {@link XmlTool} that wraps the specified
* {@link Node} from this instance's internal Node list.
+ * @return a wrapper on the nth node or null
*/
public XmlTool get(Number n)
{
@@ -486,6 +507,7 @@ public class XmlTool extends SafeConfig
/**
* Returns the first/sole {@link Node} from this
* instance's internal Node list, if any.
+ * @return the unwrapped first node or null
*/
public Node node()
{
@@ -500,6 +522,8 @@ public class XmlTool extends SafeConfig
/**
* Converts the specified object to a String and calls
* {@link #find(String)} with that.
+ * @param o xpath to search
+ * @return a wrapper on found nodes or null
*/
public XmlTool find(Object o)
{
@@ -522,6 +546,8 @@ public class XmlTool extends SafeConfig
* {@code $xml.find("a")} is equivalent to calling
* {@code $xml.find("//a")}. The full range of XPath
* selectors is supported here.
+ * @param xpath xpath to search
+ * @return a wrapper on found nodes or null
*/
public XmlTool find(String xpath)
{
@@ -556,6 +582,7 @@ public class XmlTool extends SafeConfig
* Returns a new {@link XmlTool} instance that wraps
* the parent {@link Element} of the first/sole {@link Node}
* being wrapped by this instance.
+ * @return wrapper on the parent of the first node or null
*/
public XmlTool getParent()
{
@@ -576,6 +603,7 @@ public class XmlTool extends SafeConfig
* the parent {@link Element}s of each of the {@link Node}s
* being wrapped by this instance. This does not return
* all ancestors, just the immediate parents.
+ * @return a wrapper on the set of parents nodes or null
*/
public XmlTool parents()
{
@@ -615,6 +643,7 @@ public class XmlTool extends SafeConfig
* Returns a new {@link XmlTool} instance that wraps all the
* child {@link Element}s of all the current internally held nodes
* that are {@link Element}s themselves.
+ * @return a wrapper on the children of current nodes
*/
public XmlTool children()
{
@@ -649,6 +678,7 @@ public class XmlTool extends SafeConfig
/**
* Returns the concatenated text content of all the internally held
* nodes. Obviously, this is most useful when only one node is held.
+ * @return text of current nodes or null
*/
public String getText()
{
@@ -680,6 +710,7 @@ public class XmlTool extends SafeConfig
* returns the XML (as a string) of all the internally held nodes
* that are not {@link Attr}ibutes. For attributes, only the value
* is used.
+ * @return XML string of current nodes or null
*/
public String toString()
{