Author: jkaputin
Date: Mon Apr 23 07:33:06 2007
New Revision: 531481
URL: http://svn.apache.org/viewvc?view=rev&rev=531481
Log:
Improved javadoc and refactored the toString method.
Modified:
incubator/woden/trunk/java/src/org/apache/woden/wsdl20/extensions/http/HTTPLocation.java
Modified:
incubator/woden/trunk/java/src/org/apache/woden/wsdl20/extensions/http/HTTPLocation.java
URL:
http://svn.apache.org/viewvc/incubator/woden/trunk/java/src/org/apache/woden/wsdl20/extensions/http/HTTPLocation.java?view=diff&rev=531481&r1=531480&r2=531481
==============================================================================
---
incubator/woden/trunk/java/src/org/apache/woden/wsdl20/extensions/http/HTTPLocation.java
(original)
+++
incubator/woden/trunk/java/src/org/apache/woden/wsdl20/extensions/http/HTTPLocation.java
Mon Apr 23 07:33:06 2007
@@ -26,50 +26,42 @@
/**
* This class represents the {http location} extension property of the
- * <code>BindingOperation</code> component and the <code>whttp:location</code>
extension
- * attribute of the WSDL binding <operation> element, as defined by the
+ * <code>BindingOperation</code> component which maps to the
<code>whttp:location</code>
+ * extension attribute of the WSDL binding <operation> element, as
defined by the
* WSDL 2.0 HTTP binding extensions.
- *
- * The HTTP location may be used as a template in which local names of
elements
- * from the instance data of the message to be serialized in request IRI are
- * cited by enclosing the element name within curly braces (e.g.
"temperature/{town}").
- * A curly brace-enclosed element name is substituted with the value of that
- * element from the instance data when the request IRI is constructed.
* <p>
- * This class has a single constructor which takes a String argument
representing
- * the original value of the HTTP location, which may be templated with the
curly
- * brace syntax described above. An object of this class represents only that
HTTP
- * location string (i.e. the location template cannot be modified). The class
does have
- * methods to substitute element values for local names and to return the
derived HTTP
- * location after substitution has occurred.
+ * The value of the <code>whttp:location</code> attribute may contain
templates in which elements
+ * from the instance data of the message to be serialized in the request IRI
are cited by
+ * enclosing their local name within curly braces.
+ * A template can then be substituted by matching the local name against an
element in the instance
+ * data and replacing the template in the HTTP Location with the String value
of that element.
+ * <p>
+ * For example, consider the HTTP Location "temperature/{town}" and the
message data element
+ * <code><town>Sydney</town></code>.
+ * After substitution, the formatted HTTP Location is "temperature/Sydney".
Note, that the entire
+ * template "{town}" is replaced by the matching element's value, "Sydney".
* <p>
- * This class performs syntax validation of the original HTTP location
template, checking that
- * any single left and right curly braces are used correctly as pairs
enclosing a String that
- * is of the correct format to represent an element local name (i.e. of type
xs:NCName).
- * It also handles the double curly brace syntax defined by this extension to
represent
- * literal single curly braces in the derived location value. For example,
- * "abc{{def" becomes "abc{def" in the derived location and this literal left
brace is
- * not used for matching purposes with a right curly brace.
+ * If a template is not matched against the instance data, it is replaced in
+ * the formatted HTTP Location by the empty string (in other words, it is
omitted).
* <p>
- * TODO Replace behaviour described below with new EBNF grammar added to spec
to fix this ambiguity
+ * This class has one constructor and this takes a String representing a
+ * <code>whttp:location</code> value, which may contain the curly brace
templates
+ * described above.
+ * The class can perform template substitution and return the formatted HTTP
Location
+ * resulting from such substitution. It can also return the original HTTP
Location
+ * value specified on the constructor, so that even after substitution it is
possible to
+ * see where any templates were used.
* <p>
- * The specification of the WSDL 2.0 HTTP Binding extensions does not
explicitly state how to
- * interpret extraneous, unmatched curly braces, so this class adopts the
following strategy:
+ * This class uses the EBNF grammar defined for {http location} by the
+ * WSDL 2.0 HTTP binding extensions to parse and validate the original HTTP
Location string.
+ * It checks that any single left and right curly braces are correctly paired
to enclose a String
+ * that is of the correct type to represent an element local name (that is, a
String of type
+ * xs:NCName).
* <p>
- * If multiple single left braces precede a right brace, pair the right most
one with the right
- * brace and treat the others as unmatched left braces.
- * <pre>
- * e.g. "{..{..{xxxx}"
- * </pre>
- * If multiple single right braces follow a left brace, pair the left most one
with the left
- * brace and treat the others as unmatched right braces.
- * <pre>
- * e.g. "{xxxx}..}..}"
- * </pre>
- * Double left or right braces take precedence over potentially matching pairs
of single braces.
- * <pre>
- * e.g. "{xxxx}}}" is evaluated as {xxxx,}},} not as {xxxx},}}
- * </pre>
+ * It also supports the double curly brace syntax used to represent a literal
single curly brace
+ * in the formatted HTTP Location. That is, a double curly brace escapes a
literal single curly
+ * brace to avoid mistaking it for a template. For example, "abc{{def" is
formatted as "abc{def"
+ * and this literal left brace is not interpreted as the beginning of a
template.
*
* @author John Kaputin ([EMAIL PROTECTED])
*/
@@ -92,11 +84,9 @@
leftBrace, rightBrace, doubleLeftBraces, doubleRightBraces,
exclamatedLeftBrace});
/**
- * This constructor creates an HTTPLocation object from the specified
String. This
- * String is the original value of the {http location} property, prior to
any template
- * substitution of element local names enclosed in curly braces with
element values.
- * If the property was parsed from a WSDL document, this will be the value
of the
- * <code>whttp:location</code> attribute within a binding operation
element.
+ * Creates an HTTPLocation object to represent the specified HTTP Location
String value.
+ * This String is typically the value of the <code>whttp:location</code>
attribute within
+ * a binding operation element.
* <p>
* The location template String argument must not be null.
*
@@ -121,46 +111,41 @@
}
/**
- * TODO javadoc. Method created for WODEN-148
+ * Indicates whether the original HTTP Location string used to create this
object
+ * is valid. That is, whether it can be parse according to the EBNF
grammar specified
+ * for the {http location} property by the WSDL 2.0 HTTP binding
extensions.
*
- * @return true if the format of the original HTTP location string is valid
+ * @return true if the format of the original HTTP location string is
valid,
+ * otherwise false.
*/
public boolean isLocationValid() {
return fValid;
}
/**
- * TODO javadoc. Method created for WODEN-148
+ * Returns the original HTTP Location String specified when this object
+ * was created.
*
- * @return the original String value of the HTTP location,
- * prior to any template substitution
+ * @return the original HTTP Location String
*/
public String getOriginalLocation() {
return fOriginalLocation;
}
/**
- * Same behaviour as toString()
+ * Returns a formatted String representing the original HTTP Location
modified by any
+ * template substitution that has taken place via the
<code>substitute</code> methods.
+ * Templates that have not been matched against any element from the
instance data
+ * will be omitted from the formatted String.
+ * An unmatched template is indicated by an HTTPLocationTemplate object
whose value is null.
+ * <p>
+ * If the original HTTP Location does not contain any templates then
substitution
+ * is not applicable and this method will return the same String returned
by the
+ * <code>getOriginalLocation()</code> method.
*
- * @return the formatted HTTP location, after any template substitution
+ * @return the formatted HTTP Location String, after any template
substitution
*/
public String getFormattedLocation() {
- return toString();
- }
-
- /**
- * Returns a String representing the HTTP Location template with any
element name/value
- * substitution that has taken place via the <code>substitute</code>
methods.
- * If any element local name has not yet been substituted with a value
then that
- * local name will appear in the String in its original template form,
enclosed in
- * curly braces.
- * <p>
- * If the HTTP Location does not contain any curly brace template syntax
then substitution
- * is not applicable and this method will return the same String value as
the
- * <code>getLocationTemplate()</code> method.
- */
- public String toString() {
-
StringBuffer buffer = new StringBuffer();
Object currToken;
HTTPLocationTemplate template;
@@ -172,12 +157,8 @@
template = (HTTPLocationTemplate)currToken;
String value = template.getValue();
if(value != null) {
- //the substituted element value replaces the template in
HTTP location
+ //the template is replaced in the HTTP Location by the
matching element's value
buffer.append(value);
-
- //Note, if a template value is null this indicates it has
not yet been matched to any
- //element instance data and in this case, the template is
replaced in the formatted
- //HTTP location output by the empty string "" (i.e. do
nothing here).
}
} else {
buffer.append(currToken);
@@ -188,7 +169,17 @@
}
/**
- * Return all templates in this HTTP location.
+ * Same behaviour as getFormattedLocation()
+ *
+ * @return the formatted HTTP Location String, after any template
substitution
+ */
+ public String toString() {
+ return getFormattedLocation();
+ }
+
+ /**
+ * Return the templates that appear in the HTTP Location string in
+ * the order they appear.
*
* @return an array of HTTPLocationTemplate objects
*/
@@ -209,8 +200,9 @@
}
/**
- * Return the templates in this HTTP location that appear in the path.
- * That is, before the first occurrence of "?".
+ * Return the templates that appear in the URI Path portion of the HTTP
Location
+ * string in the order they appear.
+ * This is the portion before the first occurrence of '?'.
*
* @return an array of HTTPLocationTemplate objects
*/
@@ -234,9 +226,10 @@
}
/**
- * Return the templates in this HTTP location that appear in the query.
- * That is, after the first occurrence of "?".
- *
+ * Return templates that appear in the URI Query portion of the HTTP
Location
+ * string in the order they appear.
+ * This is the portion after the first occurrence of '?'.
+ *
* @return an array of HTTPLocationTemplate objects
*/
public HTTPLocationTemplate[] getTemplatesInQuery() {
@@ -259,7 +252,10 @@
}
/**
- * Return names of all templates in this HTTP location in the order they
appear.
+ * Return the names of the templates that appear in the HTTP Location
string
+ * in the order they appear.
+ *
+ * @return a String array of template names
*/
public String[] getTemplateNames() {
List names = new Vector();
@@ -279,7 +275,11 @@
}
/**
- * Return names of all templates from the path portion of this HTTP
location in the order they appear.
+ * Return the names of the templates that appear in the URI Path portion
of the
+ * HTTP Location string in the order they appear.
+ * This is the portion before the first occurrence of '?'.
+ *
+ * @return a String array of template names
*/
public String[] getTemplateNamesInPath() {
List names = new Vector();
@@ -301,7 +301,11 @@
}
/**
- * Return names of all templates from the query portion of this HTTP
location in the order they appear.
+ * Return the names of the templates that appear in the URI Query portion
of the
+ * HTTP Location string in the order they appear.
+ * This is the portion after the first occurrence of '?'.
+ *
+ * @return a String array of template names
*/
public String[] getTemplateNamesInQuery() {
List names = new Vector();
@@ -323,7 +327,9 @@
}
/**
- * Return the first template with the specified name.
+ * Return the first template with the specified name from the HTTP
Location string.
+ *
+ * @return an HTTPLocationTemplate with the specified name
*/
public HTTPLocationTemplate getTemplate(String name) {
HTTPLocationTemplate namedTemplate = null;
@@ -340,7 +346,9 @@
}
/**
- * Return an array of templates with the specified name.
+ * Return the templates with the specified name from the HTTP Location
string .
+ *
+ * @return an array of HTTPLocationTemplates with the specified name
*/
public HTTPLocationTemplate[] getTemplates(String name) {
List namedTemplates = new Vector();
@@ -359,8 +367,10 @@
}
/**
- * Return the first template from the path with the specified name.
- * That is, before the first occurrence of "?".
+ * Return the first template with the specified name from the URI Path
portion of
+ * the HTTP Location string. This is the portion before the first
occurrence of '?'.
+ *
+ * @return an HTTPLocationTemplate with the specified name
*/
public HTTPLocationTemplate getTemplateInPath(String name) {
HTTPLocationTemplate namedTemplate = null;
@@ -377,8 +387,10 @@
}
/**
- * Return an array of templates from the path with the specified name.
- * That is, before the first occurrence of "?".
+ * Return the templates with the specified name from the URI Path portion
of the
+ * HTTP Location string. This is the portion before the first occurrence
of '?'.
+ *
+ * @return an array of HTTPLocationTemplates with the specified name
*/
public HTTPLocationTemplate[] getTemplatesInPath(String name) {
List namedTemplates = new Vector();
@@ -397,8 +409,10 @@
}
/**
- * Return the first template from the query with the specified name.
- * That is, after the first occurrence of "?".
+ * Return the first template with the specified name from the URI Query
portion of
+ * the HTTP Location string. This is the portion after the first
occurrence of '?'.
+ *
+ * @return an HTTPLocationTemplate with the specified name
*/
public HTTPLocationTemplate getTemplateInQuery(String name) {
HTTPLocationTemplate namedTemplate = null;
@@ -415,8 +429,10 @@
}
/**
- * Return an array of templates from the query with the specified name.
- * That is, after the first occurrence of "?".
+ * Return the templates with the specified name from the URI Query portion
of the
+ * HTTP Location string. This is the portion after the first occurrence of
'?'.
+ *
+ * @return an array of HTTPLocationTemplates with the specified name
*/
public HTTPLocationTemplate[] getTemplatesInQuery(String name) {
List namedTemplates = new Vector();
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
