com.sun.xml.ws.api
Class BindingID

java.lang.Object
  extended by com.sun.xml.ws.api.BindingID

public abstract class BindingID
extends Object

Parsed binding ID string.

BindingID is an immutable object that represents a binding ID, much like how URL is a representation of an URL. Like URL, this class offers a bunch of methods that let you query various traits/properties of a binding ID.

BindingID is extensible; one can plug in a parser from String to BindingID to interpret binding IDs that the JAX-WS RI does no a-priori knowledge of. Technologies such as Tango uses this to make the JAX-WS RI understand binding IDs defined in their world. Such technologies are free to extend this class and expose more characterstics.

Even though this class defines a few well known constants, BindingID instances do not necessarily have singleton semantics. Use equals(Object) for the comparison.

BindingID and WSBinding

WSBinding is mutable and represents a particular "use" of a BindingID. As such, it has state like a list of Handlers, which are inherently local to a particular usage. For example, if you have two proxies, you need two instances. BindingID, OTOH, is immutable and thus the single instance that represents "SOAP1.2/HTTP" can be shared and reused by all proxies in the same VM.


Field Summary
static com.sun.xml.ws.api.BindingID.SOAPHTTPImpl SOAP11_HTTP
          Constant that represents SOAP1.1/HTTP.
static com.sun.xml.ws.api.BindingID.SOAPHTTPImpl SOAP11_HTTP_MTOM
          Constant that represents SOAP1.1/HTTP.
static com.sun.xml.ws.api.BindingID.SOAPHTTPImpl SOAP12_HTTP
          Constant that represents SOAP1.2/HTTP.
static com.sun.xml.ws.api.BindingID.SOAPHTTPImpl SOAP12_HTTP_MTOM
          Constant that represents SOAP1.2/HTTP.
static com.sun.xml.ws.api.BindingID.SOAPHTTPImpl X_SOAP12_HTTP
          Constant that represents implementation specific SOAP1.2/HTTP which is used to generate non-standard WSDLs
static BindingID XML_HTTP
          Constant that represents REST.
 
Constructor Summary
BindingID()
           
 
Method Summary
 boolean canGenerateWSDL()
          Returns true if this binding can generate WSDL.
 WSBinding createBinding()
          Creates an instance of WSBinding (which is conceptually an "use" of BindingID) from a BindingID.
 WSBinding createBinding(javax.xml.ws.WebServiceFeature... features)
           
 WSBinding createBinding(WSFeatureList features)
           
 WebServiceFeatureList createBuiltinFeatureList()
          Returna a new WebServiceFeatureList instance that represents the features that are built into this binding ID.
abstract  Codec createEncoder(WSBinding binding)
          Creates a new Codec for this binding.
 boolean equals(Object obj)
          Compares the equality based on toString().
 String getParameter(String parameterName, String defaultValue)
          Returns a parameter of this binding ID.
abstract  SOAPVersion getSOAPVersion()
          Gets the SOAP version of this binding.
 int hashCode()
           
static BindingID parse(Class<?> implClass)
          Figures out the binding from BindingType annotation.
static BindingID parse(String lexical)
          Parses a binding ID string into a BindingID object.
abstract  String toString()
          Gets the binding ID, which uniquely identifies the binding.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

X_SOAP12_HTTP

public static final com.sun.xml.ws.api.BindingID.SOAPHTTPImpl X_SOAP12_HTTP
Constant that represents implementation specific SOAP1.2/HTTP which is used to generate non-standard WSDLs


SOAP12_HTTP

public static final com.sun.xml.ws.api.BindingID.SOAPHTTPImpl SOAP12_HTTP
Constant that represents SOAP1.2/HTTP.


SOAP11_HTTP

public static final com.sun.xml.ws.api.BindingID.SOAPHTTPImpl SOAP11_HTTP
Constant that represents SOAP1.1/HTTP.


SOAP12_HTTP_MTOM

public static final com.sun.xml.ws.api.BindingID.SOAPHTTPImpl SOAP12_HTTP_MTOM
Constant that represents SOAP1.2/HTTP.


SOAP11_HTTP_MTOM

public static final com.sun.xml.ws.api.BindingID.SOAPHTTPImpl SOAP11_HTTP_MTOM
Constant that represents SOAP1.1/HTTP.


XML_HTTP

public static final BindingID XML_HTTP
Constant that represents REST.

Constructor Detail

BindingID

public BindingID()
Method Detail

createBinding

@NotNull
public final WSBinding createBinding()
Creates an instance of WSBinding (which is conceptually an "use" of BindingID) from a BindingID.

Returns:
Always a new instance.

createBinding

@NotNull
public final WSBinding createBinding(javax.xml.ws.WebServiceFeature... features)

createBinding

@NotNull
public final WSBinding createBinding(WSFeatureList features)

getSOAPVersion

public abstract SOAPVersion getSOAPVersion()
Gets the SOAP version of this binding. TODO: clarify what to do with XML/HTTP binding

Returns:
If the binding is using SOAP, this method returns a SOAPVersion constant. If the binding is not based on SOAP, this method returns null. See Message for how a non-SOAP binding shall be handled by Tubes.

createEncoder

@NotNull
public abstract Codec createEncoder(@NotNull
                                            WSBinding binding)
Creates a new Codec for this binding.

Parameters:
binding - Ocassionally some aspects of binding can be overridden by WSBinding at runtime by users, so some Codecs need to have access to WSBinding that it's working for.

toString

public abstract String toString()
Gets the binding ID, which uniquely identifies the binding.

The relevant specs define the binding IDs and what they mean. The ID is used in many places to identify the kind of binding (such as SOAP1.1, SOAP1.2, REST, ...)

Overrides:
toString in class Object
Returns:
Always non-null same value.

createBuiltinFeatureList

public WebServiceFeatureList createBuiltinFeatureList()
Returna a new WebServiceFeatureList instance that represents the features that are built into this binding ID.

For example, BindingID for "" would always return a list that has MTOMFeature enabled.


canGenerateWSDL

public boolean canGenerateWSDL()
Returns true if this binding can generate WSDL.

For e.g.: SOAP 1.1 and "XSOAP 1.2" is supposed to return true from this method. For SOAP1.2, there is no standard WSDL, so the runtime is not generating one and it expects the WSDL is packaged.


getParameter

public String getParameter(String parameterName,
                           String defaultValue)
Returns a parameter of this binding ID.

Some binding ID, such as those for SOAP/HTTP, uses the URL query syntax (like ?mtom=true) to control the optional part of the binding. This method obtains the value for such optional parts.

For implementors of the derived classes, if your binding ID does not define such optional parts (such as the XML/HTTP binding ID), then you should simply return the specified default value (which is what this implementation does.)

Parameters:
parameterName - The parameter name, such as "mtom" in the above example.
defaultValue - If this binding ID doesn't have the specified parameter explicitly, this value will be returned.
Returns:
the value of the parameter, if it's present (such as "true" in the above example.) If not present, this method returns the defaultValue.

equals

public boolean equals(Object obj)
Compares the equality based on toString().

Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

parse

@NotNull
public static BindingID parse(String lexical)
Parses a binding ID string into a BindingID object.

This method first checks for a few known values and then delegate the parsing to BindingIDFactory.

If parsing succeeds this method returns a value. Otherwise throws WebServiceException.

Throws:
javax.xml.ws.WebServiceException - If the binding ID is not understood.

parse

@NotNull
public static BindingID parse(Class<?> implClass)
Figures out the binding from BindingType annotation.

Returns:
default to SOAP11_HTTP, if no such annotation is present.
See Also:
parse(String)