ParameterValue (JDPWS 0.11.2-SNAPSHOT API)

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

All Implemented Interfaces:

Lockable

Direct Known Subclasses:

ParameterDefinition
```
public class ParameterValue
extends java.lang.Object
implements Lockable
```
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 an 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(QName) 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 an 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 ParameterValueManagement.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 an 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.get("lastname");
 ParameterValue a = personInstance.get("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
  age.set("66");
 }
 
```
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. If an entry exists more then once, like the phone element in the example above, a 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 ParameterValueManagement 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, ParameterValueManagement

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

protected static class ParameterValue.ParameterPath
This class allows to separate the path.

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`ParameterValue.ParameterPath` This class allows to separate the path.

Field Summary

Fields
Modifier and Type	Field and Description
`protected HashMap`	`attributes`
`protected List`	`children`
`static java.lang.Object`	`EMPTY_CACHE`
`protected Type`	`instanceType`
`protected int`	`max`
`protected int`	`min`
`protected QName`	`name`
`protected boolean`	`nil`
`protected java.lang.String`	`overwrite`
`protected LockSupport`	`pvLock`
`protected Type`	`type`
`protected java.lang.String`	`uniqueIdForAttachmentDisposal`

Constructor Summary

Constructors
Constructor and Description

ParameterValue()

Constructors
Constructor and Description
`ParameterValue()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`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)`
`void`	`disposeAllAttachments()` Disposes all attachments contained in this `ParameterValue` and its children.
`void`	`exclusiveLock()` Acquires an exclusive lock.
`ParameterValue`	`get(java.lang.String path)`
`ParameterValue`	`get(java.lang.String path, Type instanceType)`
`java.lang.String`	`getAttributeValue(QName attribute)` Returns the value of an attribute for this parameter value.
`List`	`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).
`LockSupport`	`getLockObject()`
`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.
`HashMap`	`getNamespaceCache(java.lang.String comManId)`
`List`	`getNamespaces()` Returns the namespaces used by this parameter value.
`java.lang.String`	`getOverwritten()`
`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`	`isOverwritten()` Returns whether this parameter value is overridden or not.
`void`	`overwriteSerialization(java.lang.String value)` Allows to overwrite the serialization of this parameter.
`boolean`	`releaseExclusiveLock()` Releases an exclusive lock of the current thread.
`void`	`releaseSharedLock()` Releases a shared lock of the current thread.
`void`	`remove(ParameterValue value)`
`ParameterValue`	`removeChild(java.lang.String path)`
`void`	`resolveTypes(Schema s)` Resolve the types based on the given XML schema.
`void`	`setAttributes(HashMap newAttributes)`
`void`	`setAttributeValue(QName attribute, java.lang.String value)` Sets the value of an attribute of this parameter value with given value.
`void`	`setInstanceType(Type instanceType)`
`void`	`setMaxOccurs(int max)`
`void`	`setMinOccurs(int min)`
`void`	`setName(QName name)` Set the name of this parameter value.
`void`	`setNil(boolean nil)` Set whether this parameter should carry values or not.
`void`	`setType(Type type)` Set the type of this parameter value.
`void`	`sharedLock()` Acquires a shared lock.
`java.lang.String`	`toString()`
`boolean`	`tryExclusiveLock()` Try to get an exclusive lock immediately.
`boolean`	`trySharedLock()` Tries to get a shared lock immediately.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - EMPTY_CACHE
```
public static final java.lang.Object EMPTY_CACHE
```
  - overwrite
```
protected java.lang.String overwrite
```
  - type
```
protected Type type
```
  - instanceType
```
protected Type instanceType
```
  - min
```
protected int min
```
  - max
```
protected int max
```
  - nil
```
protected boolean nil
```
  - name
```
protected QName name
```
  - children
```
protected List children
```
  - attributes
```
protected HashMap attributes
```
  - pvLock
```
protected LockSupport pvLock
```
  - uniqueIdForAttachmentDisposal
```
protected java.lang.String uniqueIdForAttachmentDisposal
```
- Constructor Detail
  - ParameterValue
```
public ParameterValue()
```
- Method Detail
  - getNamespaceCache
```
public HashMap getNamespaceCache(java.lang.String comManId)
```
  - 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.
  - 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.
  - overwriteSerialization
```
public void overwriteSerialization(java.lang.String value)
```
    Allows to overwrite 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 overwritten too.
    
    Set to null to disable the overwrite.
    
    Parameters:
    
    value - the value which should overwrite the parameter serialization, or null if the parameter should not be overridden.
  - isOverwritten
```
public boolean isOverwritten()
```
    Returns whether this parameter value is overridden or not.
    
    Returns:
    
    true the parameter serialization is overridden, false otherwise.
  - getOverwritten
```
public java.lang.String getOverwritten()
```
  - setAttributeValue
```
public void setAttributeValue(QName 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(QName 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. !!Be careful to hold a shared lock on this parameter value while using the returned Iterator.!!
    
    Returns:
    
    an iterator of attributes for this parameter value.
  - setAttributes
```
public void setAttributes(HashMap newAttributes)
```
  - 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
  - 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.
  - 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"
  - getType
```
public Type getType()
```
    Returns the type of this parameter value.
    
    Returns:
    
    the parameter value.
  - setType
```
public void setType(Type type)
```
    Set the type of this parameter value.
    
    Parameters:
    
    type - the type.
  - getLockObject
```
public LockSupport getLockObject()
```
  - 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.
  - setInstanceType
```
public void setInstanceType(Type instanceType)
```
  - 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.
  - setMinOccurs
```
public void setMinOccurs(int min)
```
  - 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.
  - setMaxOccurs
```
public void setMaxOccurs(int max)
```
  - 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
  - setName
```
public void setName(QName name)
```
    Set the name of this parameter value.
    
    Parameters:
    
    name - the 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()
```
    Returns the number of inner-elements for the parameter value.
    
    Returns:
    
    the amount of inner-elements.
  - 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.
  - getChildren
```
public List 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)
```
  - get
```
public ParameterValue get(java.lang.String path)
                   throws java.lang.IndexOutOfBoundsException,
                          java.lang.IllegalArgumentException
```
    Throws:
    
    java.lang.IndexOutOfBoundsException
    
    java.lang.IllegalArgumentException
  - get
```
public ParameterValue get(java.lang.String path,
                          Type instanceType)
                   throws java.lang.IndexOutOfBoundsException,
                          java.lang.IllegalArgumentException
```
    Throws:
    
    java.lang.IndexOutOfBoundsException
    
    java.lang.IllegalArgumentException
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - sharedLock
```
public void sharedLock()
```
    Description copied from interface: Lockable
    
    Acquires a shared lock. If the lock cannot be allocated immediately, the thread is blocked until allocation is possible.
    
    Specified by:
    
    sharedLock in interface Lockable
  - exclusiveLock
```
public void exclusiveLock()
```
    Description copied from interface: Lockable
    
    Acquires an exclusive lock. If the lock cannot be allocated immediately, the thread is blocked until allocation is possible.
    
    Specified by:
    
    exclusiveLock in interface Lockable
  - trySharedLock
```
public boolean trySharedLock()
```
    Description copied from interface: Lockable
    
    Tries to get a shared lock immediately.
    
    Specified by:
    
    trySharedLock in interface Lockable
    
    Returns:
    
    true if the lock has been allocated, false otherwise
  - tryExclusiveLock
```
public boolean tryExclusiveLock()
```
    Description copied from interface: Lockable
    
    Try to get an exclusive lock immediately.
    
    Specified by:
    
    tryExclusiveLock in interface Lockable
    
    Returns:
    
    true if the lock has been allocated, false otherwise
  - releaseSharedLock
```
public void releaseSharedLock()
```
    Description copied from interface: Lockable
    
    Releases a shared lock of the current thread.
    
    Specified by:
    
    releaseSharedLock in interface Lockable
  - releaseExclusiveLock
```
public boolean releaseExclusiveLock()
```
    Description copied from interface: Lockable
    
    Releases an exclusive lock of the current thread.
    
    Specified by:
    
    releaseExclusiveLock in interface Lockable
    
    Returns:
    
    true = if last exclusive lock of this thread is released.
  - disposeAllAttachments
```
public void disposeAllAttachments()
```
    Disposes all attachments contained in this ParameterValue and its children. It is important to call this method for incoming ParameterValues to allow the attachment store to clean up the attachment data.
    
    Notice
    
    This Method does only work for the root ParameterValue which was returned by an invoke call on an Operation.

Class ParameterValue

XML Schema

Framework

Details

Notice

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EMPTY_CACHE

overwrite

type

instanceType

min

max

nil

name

children

attributes

pvLock

uniqueIdForAttachmentDisposal

Constructor Detail

ParameterValue

Method Detail

getNamespaceCache

getNamespaces

getValueType

overwriteSerialization

NOTICE:

isOverwritten

getOverwritten

setAttributeValue

getAttributeValue

add

addAnyAttribute

hasAttributes

attributes

setAttributes

attributeNames

isNil

setNil

getType

setType

getLockObject

getInstanceType

setInstanceType

getMinOccurs

setMinOccurs

getMaxOccurs

setMaxOccurs

getName

setName

add

remove

hasChildren

getChildrenCount

getChildrenCount

getChildren

hasChildrenFromType

childrenFromType

children

getChildrenList

resolveTypes

removeChild

createChild

createChild

get

get

toString

sharedLock

exclusiveLock

trySharedLock

tryExclusiveLock

releaseSharedLock

releaseExclusiveLock

disposeAllAttachments

Notice