org.ws4d.java.service.parameter
Class ParameterValue

java.lang.Object
  org.ws4d.java.service.parameter.ParameterValue

Direct Known Subclasses:

ParameterDefinition

public class ParameterValue
extends java.lang.Object

This class allows object representation of XML instance documents.

XML Schema describes the structure of content for XML instance documents. Those definitions are used inside WSDL documents to describe a message's content. It is possible to define XML Schema structures with the classes Schema, Element, Attribute, SimpleType, ComplexType, Group and AttributeGroup. This is at least necessary to invoke SOAP operations (like used in DPWS).
A complex type consists of a qualified name and the description of the content structure.

XML Schema

XML Schema describes the structure of the content for a XML instance document. Each element is dedicated to a specific data type. XML Schema comes with built-in primitive data types like string, boolean, decimal and derived data types like byte, int, token and positiveInteger. It is also possible to define one's own derived data types. An XML Schema could look like this:

 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org"> 
    <xs:complexType name="personType">
       <xs:sequence>
          <xs:element name="firstname" type="xs:string" />
          <xs:element name="lastname" type="xs:string" />
          <xs:element name="age" type="xs:int" />
       </xs:sequence>
    </xs:complexType>
    <xs:element name="person" type="personType" />
 </xs:schema>
 

The XML Schema above defines a derived data type called personType which contains inner-elements. The derived data type is used by the element person. This XML schema allows the creation of the following XML instance document:

 <?xml version="1.0"?>
 <person>
    <firstname>John</firstname>
    <lastname>Doe</lastname>
    <age>66</age>
 </person>
 

You can learn more about XML Schema at http://www.w3.org/XML/Schema

Framework

If you want to create the complex type described above, it is necessary to create the derived data type too and use the primitive data type string. If you can access predefined primitive data types with the SchemaUtil.getSchemaType(String) method.
The created code should look like this:

 // get primitive data types
 Type xsString = SchemaUtil.getSchemaType("string");
 Type xsInt = SchemaUtil.getSchemaType("int");
 
 // create inner elements for personType
 Element firstname = new Element(new QName("firstname", "http://www.example.org"), xsString);
 Element lastname = new Element(new QName("lastname", "http://www.example.org"), xsString);
 Element age = new Element(new QName("age", "http://www.example.org"), xsInt);
 
 // create personType and add inner elements
 ComplexType personType = new ComplexType(new QName("personType", "http://www.example.org"), ComplexType.CONTAINER_SEQUENCE);
 personType.addElement(firstname);
 personType.addElement(lastname);
 personType.addElement(age);
 
 // create element
 Element person = new Element(new QName("person", "http://www.example.org"), personType);
 

Details

The person element defined above can be used as input or output parameter of an operation. This will allow to use this parameter within a service. As shown in the XML Schema part, an element defined inside a XML Schema will be used to create XML instance documents. The Framework allows to create those XML instance documents with this class. A parameter value can be created from an element with the createElementValue(Element) method, or will be pass-through within action invocation.

The ParameterValue class allows nested structures like seen in XML. An object of this class represents a single entry in a XML instance document. The XML shown above, has an root element named "person" containing three inner-elements, firstname, lastname and age.
This would lead to an parameter value with three nested inner-elements. The ParameterValue class allows to access the element directly and any inner-element. To access the value of a parameter it is necessary to check the type of the parameter and cast to the correct implementation. The framework comes along with the implementation of xs:string StringValue, xs:QNAME QNameValue and xs:base64binary AttachmentValue. It is possible to register own implementation of XML Schema datatypes. If no implementation matches the given data type a it will be handles as xs:string (fallback). The following lines of code, will show the usage for the structure defined above:

 // create ParameterValue from element
 ParameterValue personInstance = ParameterValue.createElementValue(person);
 
 // as person does not have any values to set, set the value of the
 // inner-elements.
 // direct access using the path (something like XPath).
 ParameterValue fname = personInstance.get("firstname");
 ParameterValue lname = personInstance.setValue("lastname");
 ParameterValue a = personInstance.setValue("age");
 
 // check for correct type, cast and set the value
 if (fname.getValueType() == ParameterValue.TYPE_STRING) {
        StringValue firstname = (StringValue) fname;
        // set value for the string
        firstname.set("John");
 }
 
 if (lname.getValueType() == ParameterValue.TYPE_STRING) {
        StringValue lastname = (StringValue) lname;
        // set value for the string
        lastname.set("Doe");
 }
 
 // As there is not implementation for xs:integer we must use the xs:string
 // fallback here
 if (a.getValueType() == ParameterValue.TYPE_STRING) {
        StringValue age = (StringValue) a;
        // set value for the string
        lastname.set("66");
 }
 
 // check for correct type, cast and set the value
 if (fname.getValueType() == ParameterValue.TYPE_STRING) {
        StringValue firstname = (StringValue) fname;
        // set value for the string
        String fn = firstname.get();
 }
 

The path value used in different methods, allows direct access the inner-elements. Let us assume the XML content below:

 <?xml version="1.0"?>
 <person>
    <firstname>John</firstname>
    <lastname>Doe</lastname>
    <age>66</age>
    <address>
       <street>Mainstreet 20</firstname>
       <city>Los Wochos</lastname>
       <phone>555-123-780-JOHNDOE</phone>
       <phone>555-123-780-XML</phone>
    </address>
 </person>
 

To access the elements like street, or even the both phone elements, it necessary to extend the path. The path is always relative to the current element. Every next entry in the path is divided by a slash (\). No set path points the current element. You can use the #setValue(String) and #getValue() methods for direct access without path. If an entry exists more then once, like the phone element in the example above, an specific element can be accessed by using an index. The index starts with 0. Omitting the index is like using 0.

path syntax: child[index]/child-from-child[index]/child-from-child-from-chil[index]/ ... and so on.

 // create ParameterValue from element
 ParameterValue personInstance = ParameterValue.createElementValue(person);
 
 // as person does not have any values to set, set the value of the
 // inner-elements.
 // direct access using the path (something like XPath).
 personInstance.get("firstname");
 

Notice

The ParameterUtil class offers shortcut methods for the most common cast, get and set operations for the build-in implementation of datatypes.

See Also:

Element, Operation, StringValue, QNameValue, AttachmentValue, ParameterUtil

Field Summary

static boolean	ALLOW_NOINDEX
static int	TYPE_ATTACHMENT
static int	TYPE_COMPLEX
static int	TYPE_QNAME
static int	TYPE_STRING
static int	TYPE_UNKNOWN

Constructor Summary

ParameterValue()

Method Summary

void	add(ParameterAttribute attribute)
void	add(ParameterValue value) Adds an inner-element to this parameter value.
void	addAnyAttribute(QName name, java.lang.String value)
Iterator	attributeNames() Returns an iterator over the qualified names of all attributes within this parameter value.
Iterator	attributes() Returns an iterator of attributes for this parameter value.
static int	childCount(ParameterValue pv, java.lang.String childLocalName) Returns the number of direct children of pv with a local name of childLocalName.
Iterator	children() Returns an iterator of inner-elements for this parameter value.
Iterator	childrenFromType() Returns an iterator of types for all inner-elements.
ParameterValue	createChild(java.lang.String path)
ParameterValue	createChild(java.lang.String path, Type instanceType)
static ParameterValue	createElementValue(Element element) Creates an XML instance document representation from a given XML Schema element.
static ParameterValue	createElementValue(Element element, Type instanceType)
ParameterValue	get(java.lang.String path)
java.lang.String	getAttributeValue(java.lang.String attribute) Returns the value of an attribute for this parameter value.
Iterator	getChildren(java.lang.String path) Returns an iterator of inner-elements for the parameter value given by the path.
int	getChildrenCount() Returns the number of inner-elements for the parameter value.
int	getChildrenCount(java.lang.String path) Returns the number of inner-elements for the parameter value given by the path.
ListIterator	getChildrenList() Returns an listiterator of inner-elements for this parameter value.
Type	getInstanceType() Returns the instance type of this parameter value (in accordance to xsi:Type attribute).
int	getMaxOccurs() Returns the the maximum occurrence for this parameter value.
int	getMinOccurs() Returns the the minimum occurrence for this parameter value.
QName	getName() Returns the name of the parameter value.
List	getNamespaces() Returns the namespaces used by this parameter value.
Type	getType() Returns the type of this parameter value.
int	getValueType() Returns the VALUE TYPE for this parameter.
boolean	hasAttributes() Returns true if this parameter value has attributes, false otherwise.
boolean	hasChildren() Returns true if this parameter value has inner-elements, false otherwise.
boolean	hasChildrenFromType() Returns true if this parameter value is based on a complex type, false otherwise.
boolean	isNil() Returns whether the XML instance nil value is set or not.
boolean	isOverriden() Returns whether this parameter value is overridden or not.
void	overrideSerialization(java.lang.String value) Allows to override the serialization of this parameter.
static java.lang.String	register(Type type, java.lang.String clazz) Register a class for a XML Schema datatype Type.
void	remove(ParameterValue value)
ParameterValue	removeChild(java.lang.String path)
void	resolveTypes(Schema s) Resolve the types based on the given XML schema.
void	serialize(java.io.OutputStream out) Serializes the parameter value into an XML instance document on a given stream.
void	serialize(org.xmlpull.v1.XmlSerializer serializer) Serializes the parameter value with a XML serializer.
void	setAttributeValue(java.lang.String attribute, java.lang.String value) Sets the value of an attribute of this parameter value with given value.
void	setInstanceType(Type instanceType)
void	setNil(boolean nil) Set whether this parameter should carry values or not.
java.lang.String	toString()
static java.lang.String	unregister(Type type) Unregister a class for a XML Schema datatype Type.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ALLOW_NOINDEX

public static final boolean ALLOW_NOINDEX

See Also:

Constant Field Values

TYPE_UNKNOWN

public static final int TYPE_UNKNOWN

See Also:

Constant Field Values

TYPE_COMPLEX

public static final int TYPE_COMPLEX

See Also:

Constant Field Values

TYPE_STRING

public static final int TYPE_STRING

See Also:

Constant Field Values

TYPE_ATTACHMENT

public static final int TYPE_ATTACHMENT

See Also:

Constant Field Values

TYPE_QNAME

public static final int TYPE_QNAME

See Also:

Constant Field Values

Constructor Detail

ParameterValue

public ParameterValue()

Method Detail

getNamespaces

public List getNamespaces()

Returns the namespaces used by this parameter value.

This method allows to collect all namespaces and use it if necessary.

Returns:

a List of QName.

register

public static java.lang.String register(Type type,
                                        java.lang.String clazz)

Register a class for a XML Schema datatype Type.

Parameters:

type - the type which should be used.

clazz - the class which should be used to handle that type.

Returns:

the classname if already set.

unregister

public static java.lang.String unregister(Type type)

Unregister a class for a XML Schema datatype Type.

Parameters:

type - the type which should be used.

Returns:

the classname.

getValueType

public int getValueType()

Returns the VALUE TYPE for this parameter.

A VALUE TYPE should be a unique representation of a ParameterValue implementation which allows to identify the implementation and cast correctly.

Returns:

the VALUE TYPE.

overrideSerialization

public void overrideSerialization(java.lang.String value)

Allows to override the serialization of this parameter.

NOTICE:

The given String can contain anything but SHOULD contain correct XML data. This method should be used for debug purposes. A nested parameter can be overriden too.

Set to null to disable the override.

Parameters:

value - the value which should override the parameter serialization, or null if the parameter should not be overridden.

isOverriden

public boolean isOverriden()

Returns whether this parameter value is overridden or not.

Returns:

true the parameter serialization is overridden, false otherwise.

setAttributeValue

public void setAttributeValue(java.lang.String attribute,
                              java.lang.String value)

Sets the value of an attribute of this parameter value with given value.

Parameters:

attribute - the name of the attribute.

value - the value of the attribute.

getAttributeValue

public java.lang.String getAttributeValue(java.lang.String attribute)

Returns the value of an attribute for this parameter value.

Parameters:

attribute - the attribute to get the value of.

Returns:

the value of the attribute.

add

public void add(ParameterAttribute attribute)

addAnyAttribute

public void addAnyAttribute(QName name,
                            java.lang.String value)

hasAttributes

public boolean hasAttributes()

Returns true if this parameter value has attributes, false otherwise.

Returns:

true if this parameter value has attributes, false otherwise.

attributes

public Iterator attributes()

Returns an iterator of attributes for this parameter value.

Returns:

an iterator of attributes for this parameter value.

attributeNames

public Iterator attributeNames()

Returns an iterator over the qualified names of all attributes within this parameter value.

Returns:

an iterator over QName instances, which represent the names of this parameter value's attributes

setInstanceType

public void setInstanceType(Type instanceType)

setNil

public void setNil(boolean nil)

Set whether this parameter should carry values or not.

Parameters:

nil - true this parameter will not have any values and the XML instance nil will be set. xsi:nil="true"

isNil

public boolean isNil()

Returns whether the XML instance nil value is set or not.

Returns:

true if the XML instance nil value is set, false otherwise.

getType

public Type getType()

Returns the type of this parameter value.

Returns:

the parameter value.

getInstanceType

public Type getInstanceType()

Returns the instance type of this parameter value (in accordance to xsi:Type attribute). If no instance type is set, the declared type is returned.

Returns:

the instance type of the parameter value.

getMinOccurs

public int getMinOccurs()

Returns the the minimum occurrence for this parameter value.

The "minOccurs" attribute in XML Schema describes the minimum occurrence of this element inside the created XML instance document.

Returns:

the minimum occurrence of this parameter value.

getMaxOccurs

public int getMaxOccurs()

Returns the the maximum occurrence for this parameter value.

The "maxOccurs" attribute in XML Schema describes the maximum occurrence of this element inside the created XML instance document.

Returns:

the maximum occurrence of this parameter value.

getName

public QName getName()

Returns the name of the parameter value. The name of the parameter value is the name of the entry inside the XML document.

Returns:

the parameter value name

add

public void add(ParameterValue value)

Adds an inner-element to this parameter value. This method is necessary to create nested structures.

Parameters:

value - the parameter value to add.

remove

public void remove(ParameterValue value)

hasChildren

public boolean hasChildren()

Returns true if this parameter value has inner-elements, false otherwise.

Returns:

true if this parameter value has inner-elements, false otherwise.

getChildrenCount

public int getChildrenCount(java.lang.String path)

Returns the number of inner-elements for the parameter value given by the path.

Parameters:

path - the path to access the inner-element.

Returns:

the amount of inner-elements.

getChildrenCount

public int getChildrenCount()

Returns the number of inner-elements for the parameter value.

Parameters:

path - the path to access the inner-element.

Returns:

the amount of inner-elements.

getChildren

public Iterator getChildren(java.lang.String path)

Returns an iterator of inner-elements for the parameter value given by the path.

Parameters:

path - the path to access the inner-element.

Returns:

iterator of inner-elements.

hasChildrenFromType

public boolean hasChildrenFromType()

Returns true if this parameter value is based on a complex type, false otherwise.

Returns:

true if this parameter value is based on a complex type, false otherwise.

childrenFromType

public Iterator childrenFromType()

Returns an iterator of types for all inner-elements.

Returns:

an iterator of types for all inner-elements.

children

public Iterator children()

Returns an iterator of inner-elements for this parameter value.

Returns:

an iterator of inner-elements for this parameter value.

getChildrenList

public ListIterator getChildrenList()

Returns an listiterator of inner-elements for this parameter value.

Returns:

an listiterator of inner-elements for this parameter value.

resolveTypes

public void resolveTypes(Schema s)

Resolve the types based on the given XML schema.

Parameters:

s - the XML schema which contains the types for this parameter value.

removeChild

public ParameterValue removeChild(java.lang.String path)

createChild

public ParameterValue createChild(java.lang.String path)

createChild

public ParameterValue createChild(java.lang.String path,
                                  Type instanceType)

serialize

public void serialize(org.xmlpull.v1.XmlSerializer serializer)
               throws java.io.IOException

Serializes the parameter value with a XML serializer.

Parameters:

serializer - the XML serializer.

Throws:

java.io.IOException - throws an exception if the parameter value could not be serialized correctly.

serialize

public void serialize(java.io.OutputStream out)
               throws java.io.IOException

Serializes the parameter value into an XML instance document on a given stream.

Parameters:

out - the stream to serialize to.

Throws:

java.io.IOException - throws an exception if the parameter value could not be serialized correctly.

get

public ParameterValue get(java.lang.String path)
                   throws java.lang.IndexOutOfBoundsException,
                          java.lang.IllegalArgumentException

Throws:

java.lang.IndexOutOfBoundsException

java.lang.IllegalArgumentException

createElementValue

public static ParameterValue createElementValue(Element element)

Creates an XML instance document representation from a given XML Schema element.

Parameters:

element - the element to create the representation from.

Returns:

the XML instance document representation.

createElementValue

public static ParameterValue createElementValue(Element element,
                                                Type instanceType)

childCount

public static int childCount(ParameterValue pv,
                             java.lang.String childLocalName)

Returns the number of direct children of pv with a local name of childLocalName. Returns 0, if either pv or childLocalName are null.

Parameters:

pv - the parameter value instance, which of to count the direct children with the given local name

childLocalName - the local name of children to look for

Returns:

the number of direct children of pv with the specified local name

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object