org.apache.woden.wsdl20.extensions.http

## Class HTTPLocation

- java.lang.Object
- - org.apache.woden.wsdl20.extensions.http.HTTPLocation

-     public class HTTPLocation
      extends Object

  This class represents the {http location} extension property of the `BindingOperation` component which maps to the `whttp:location` extension attribute of the WSDL binding <operation> element, as defined by the WSDL 2.0 HTTP binding extensions.

  The value of the `whttp:location` 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.

  For example, consider the HTTP Location "temperature/{town}" and the message data element `<town>Sydney</town>`. After substitution, the formatted HTTP Location is "temperature/Sydney". Note, that the entire template "{town}" is replaced by the matching element's value, "Sydney".

  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).

  This class has one constructor and this takes a String representing a `whttp:location` 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.

  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).

  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)

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `HTTPLocation(String location)` Creates an HTTPLocation object to represent the specified HTTP Location String value.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getFormattedLocation()` Returns a formatted String representing the original HTTP Location modified by any template substitution that has taken place via the `substitute` methods.
    `String` | `getOriginalLocation()` Returns the original HTTP Location String specified when this object was created.
    `HTTPLocationTemplate` | `getTemplate(String name)` Return the first template with the specified name from the HTTP Location string or null if no such template is exists.
    `HTTPLocationTemplate` | `getTemplateInPath(String name)` Return the first template with the specified name from the URI Path portion of the HTTP Location string or null if no such template exists.
    `HTTPLocationTemplate` | `getTemplateInQuery(String name)` Return the first template with the specified name from the URI Query portion of the HTTP Location string or null if no such template exists.
    `String[]` | `getTemplateNames()` Return the names of the templates that appear in the HTTP Location string in the order they appear.
    `String[]` | `getTemplateNamesInPath()` Return the names of the templates that appear in the URI Path portion of the HTTP Location string in the order they appear.
    `String[]` | `getTemplateNamesInQuery()` Return the names of the templates that appear in the URI Query portion of the HTTP Location string in the order they appear.
    `HTTPLocationTemplate[]` | `getTemplates()` Return the templates that appear in the HTTP Location string in the order they appear.
    `HTTPLocationTemplate[]` | `getTemplates(String name)` Return the templates with the specified name from the HTTP Location string .
    `HTTPLocationTemplate[]` | `getTemplatesInPath()` Return the templates that appear in the URI Path portion of the HTTP Location string in the order they appear.
    `HTTPLocationTemplate[]` | `getTemplatesInPath(String name)` Return the templates with the specified name from the URI Path portion of the HTTP Location string.
    `HTTPLocationTemplate[]` | `getTemplatesInQuery()` Return templates that appear in the URI Query portion of the HTTP Location string in the order they appear.
    `HTTPLocationTemplate[]` | `getTemplatesInQuery(String name)` Return the templates with the specified name from the URI Query portion of the HTTP Location string.
    `boolean` | `isLocationValid()` Indicates whether the original HTTP Location string used to create this object is valid.
    `String` | `toString()` Same behaviour as getFormattedLocation()

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### HTTPLocation

          public HTTPLocation(String location)

      Creates an HTTPLocation object to represent the specified HTTP Location String value. This String is typically the value of the `whttp:location` attribute within a binding operation element.

      The location template String argument must not be null.

      Parameters:
        `location` - the String value of the http location

  - ### Method Detail

    - #### isLocationValid

          public boolean isLocationValid()

      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.
      Returns:
        true if the format of the original HTTP location string is valid, otherwise false.

    - #### getOriginalLocation

          public String getOriginalLocation()

      Returns the original HTTP Location String specified when this object was created.
      Returns:
        the original HTTP Location String

    - #### getFormattedLocation

          public String getFormattedLocation()

      Returns a formatted String representing the original HTTP Location modified by any template substitution that has taken place via the `substitute` 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.

      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 `getOriginalLocation()` method.

      If the HTTP Locationis invalid this method will return null.

      Returns:
        the formatted HTTP Location String, after any template substitution

    - #### toString

          public String toString()

      Same behaviour as getFormattedLocation()
      Overrides:
        `toString` in class `Object`
      Returns:
        the formatted HTTP Location String, after any template substitution

    - #### getTemplates

          public HTTPLocationTemplate[] getTemplates()

      Return the templates that appear in the HTTP Location string in the order they appear. If the HTTP Location contains no templates or if it is invalid this method will return an empty array.
      Returns:
        an array of HTTPLocationTemplate objects

    - #### getTemplatesInPath

          public HTTPLocationTemplate[] getTemplatesInPath()

      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 '?'. If the HTTP Location contains no templates in the Path or if it is invalid this method will return an empty array.
      Returns:
        an array of HTTPLocationTemplate objects

    - #### getTemplatesInQuery

          public HTTPLocationTemplate[] getTemplatesInQuery()

      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 '?'. If the HTTP Location contains no templates in the Query or if it is invalid this method will return an empty array.
      Returns:
        an array of HTTPLocationTemplate objects

    - #### getTemplateNames

          public String[] getTemplateNames()

      Return the names of the templates that appear in the HTTP Location string in the order they appear. If the HTTP Location contains no templates or if it is invalid this method will return an empty array.
      Returns:
        a String array of template names

    - #### getTemplateNamesInPath

          public String[] getTemplateNamesInPath()

      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 '?'. If the HTTP Location contains no templates in the Path or if it is invalid this method will return an empty array.
      Returns:
        a String array of template names

    - #### getTemplateNamesInQuery

          public String[] getTemplateNamesInQuery()

      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 '?'. If the HTTP Location contains no templates in the Query or if it is invalid this method will return an empty array.
      Returns:
        a String array of template names

    - #### getTemplate

          public HTTPLocationTemplate getTemplate(String name)

      Return the first template with the specified name from the HTTP Location string or null if no such template is exists.

      If the HTTP Location is invalid this method will return null.

      Returns:
        an HTTPLocationTemplate with the specified name

    - #### getTemplates

          public HTTPLocationTemplate[] getTemplates(String name)

      Return the templates with the specified name from the HTTP Location string . If the HTTP Location contains no such templates or if it is invalid this method will return an empty array.
      Returns:
        an array of HTTPLocationTemplates with the specified name

    - #### getTemplateInPath

          public HTTPLocationTemplate getTemplateInPath(String name)

      Return the first template with the specified name from the URI Path portion of the HTTP Location string or null if no such template exists. The Path is the portion before the first occurrence of '?'.

      If the HTTP Location is invalid this method will return null.

      Returns:
        an HTTPLocationTemplate with the specified name

    - #### getTemplatesInPath

          public HTTPLocationTemplate[] getTemplatesInPath(String name)

      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 '?'. If the HTTP Location contains no such templates in the Path or if it is invalid this method will return an empty array.
      Returns:
        an array of HTTPLocationTemplates with the specified name

    - #### getTemplateInQuery

          public HTTPLocationTemplate getTemplateInQuery(String name)

      Return the first template with the specified name from the URI Query portion of the HTTP Location string or null if no such template exists. The Query is the portion after the first occurrence of '?'.

      If the HTTP Location is invalid this method will return null.

      Returns:
        an HTTPLocationTemplate with the specified name

    - #### getTemplatesInQuery

          public HTTPLocationTemplate[] getTemplatesInQuery(String name)

      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 '?'. If the HTTP Location contains no such templates in the Query or if it is invalid this method will return an empty array.
      Returns:
        an array of HTTPLocationTemplates with the specified name

Copyright ? Apache Software Foundation. All Rights Reserved.