ws-woden-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jkapu...@apache.org
Subject svn commit: r531481 - /incubator/woden/trunk/java/src/org/apache/woden/wsdl20/extensions/http/HTTPLocation.java
Date Mon, 23 Apr 2007 14:33:13 GMT
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 &lt;operation&gt; element, as defined by the
+ * <code>BindingOperation</code> component which maps to the <code>whttp:location</code>

+ * extension attribute of the WSDL binding &lt;operation&gt; 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>&lt;town&gt;Sydney&lt;/town&gt;</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 (jkaputin@apache.org)
  */
@@ -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: woden-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: woden-dev-help@ws.apache.org


Mime
View raw message