com.idimiddleware.objectq

Class Attribute

java.lang.Object

com.idimiddleware.objectq.Attribute

public class Attribute
extends java.lang.Object

The CMIS-style messages supported by the Message class pass data as one of the three types of list:

• attribute identifier list, which is a list of the unique identifiers representing attributes,
• attribute list, which is a list of attribute id/value pairs, or
• modification list, which is a list of attribute id/value/operation triples.

Attribute identifiers

An attribute identifier is either a registered name or a domain/name pair. The registered name is actually a long, written as A.B.C.D, where each letter represents, in decimal, some part of the full identifier value, in a similar way to IP addresses. Because the registered name is unwieldy to use and remember, attributes may also be identified by a domain/name pair, where both are character strings. The domain is unique, but the name need only be unique within the domain. The registered name can be determined from the cpAttributeTable class.
Attributes will normally have only an attribute name, but may also have a class name where it is necessary to distinguish between the same attribute in two or more different classes. Attribute constructors may specify the class/attribute names in either of two formats: as an attribute name only ("tt.name"), or as a class/attribute pair ("tt.contact.tt.name").

Attribute values

Attribute value types can be any one of A_CHAR (1 byte), A_SHORT (2 bytes), A_LONG (4 bytes), A_OCTETS (a byte array), A_STRING (a string), A_ARRAY (an array of like attributes), A_COMPLEX (a composite of any of the primitive types) or A_REFER (of the same type as the referred-to attribute).
When attributes are initialized (either at construction time, or subsequently by setting the value), the type of the value supplied must match with the type associated with the registered name (specified in the Attribute Table). If not, the attributes value will be silently set to null. When an attribute of type A_COMPLEX is constructed, the complete hierarchy will also be constructed, so that the subList will point to the component attributes; all the component attributes’ values will be initially set to null, and the user must traverse the hierarchy to set the values.
When an attribute of type A_REFER is constructed, its type is immediately replaced by the type of the referred-to attribute, so that, in practice, an actual attribute can never be of type A_REFER.

Operations

An operation is one of the CMIS-defined O_REPLACE, O_ADD_VALUE, O_REMOVE_VALUE or O_DEFAULT, or a relational operator O_EQUAL, O_NEQUAL, O_GREATER_THAN, O_LESS_THAN, O_GT_EQUAL or O_LT_EQUAL.

Sublists

Attributes of type A_COMPLEX or A_ARRAY have component attributes in a sublist. Those components may themselves have components, so that hierarchical structures of arbitrary complexity may be built up. When an attribute of type A_COMPLEX is constructed, the complete hierarchy (with null values) is automatically constructed beneath it — the user must traverse the hierarchy to populate the actual values. The list associated with an attribute of type A_ARRAY is initially empty. The sublists should never be accessed directly — values can be set or retrieved from a complex or array attribute using find(), and components can be added to an array attribute using reserve().

Constructor Summary

Constructors

Constructor and Description
Attribute() Construct an attribute with default values.
Attribute(java.lang.String attrName) Construct an attribute with the specified name, expressed as a string.
Attribute(java.lang.String attrName, char value) Construct a char attribute with an initial value.
Attribute(java.lang.String attrName, int value) Construct a long attribute with an initial value.
Attribute(java.lang.String attrName, OctetString value) Construct an octet-string attribute with an initial value.
Attribute(java.lang.String attrName, short value) Construct a short attribute with an initial value.
Attribute(java.lang.String attrName, java.lang.String value) Construct a string attribute with an initial value.
Attribute(java.lang.String className, java.lang.String attrName, char value) Construct a char attribute with an initial value.
Attribute(java.lang.String className, java.lang.String attrName, int value) Construct a long attribute with an initial value.
Attribute(java.lang.String className, java.lang.String attrName, OctetString value) Construct an octet-string attribute with an initial value.
Attribute(java.lang.String className, java.lang.String attrName, short value) Construct a short attribute with an initial value.
Attribute(java.lang.String className, java.lang.String attrName, java.lang.String value) Construct a string attribute with an initial value.

Method Summary

Modifier and Type	Method and Description
Attribute	find(java.lang.String component)
java.lang.String	getAttrDomain() Get the domain name.
java.lang.String	getAttrFullName() Get the full attribute name - domain-name.attribute-name.
java.lang.String	getAttrName() Get the attribute name - without the domain-name.
ObjectQ.Operator	getAttrOp() Get the attribute's operation.
ObjectQ.AttributeType	getAttrType() Get the attribute's type.
char	getCharValue() Get the value of an attribute of type char.
char	getCharValue(java.lang.String component) Get the char value associated with an attribute.
java.lang.String	getClassName() Get the attribute's classname.
int	getLongValue() Get the value of an attribute of type long (which is really an int).
int	getLongValue(java.lang.String component) Get the long value associated with an attribute (which is really an int).
OctetString	getOctetStringValue() Get the value of an attribute of type octet-string.
OctetString	getOctetStringValue(java.lang.String component) Get the octet-string value associated with an attribute.
short	getShortValue() Get the value of an attribute of type short.
short	getShortValue(java.lang.String component) Get the short value associated with an attribute.
java.lang.String	getStringValue() Get the value of an attribute of type string.
java.lang.String	getStringValue(java.lang.String component) Get the string value associated with an attribute.
void	reserve(int n) Add elements to an array if necessary to ensure that index n is accessible.
Attribute	restore(byte[] bytes, boolean idsOnly) Restore an attribute from a previously flattened byte stream.
byte[]	save(boolean idsOnly) Save an attribute or attribute id to a byte stream.
void	setAttrOp(ObjectQ.Operator attrOp) Set the attribute's operation.
void	setValue(char value) Set the value of an attribute of type char.
void	setValue(int value) Set the value of an attribute of type long.
void	setValue(OctetString value) Set the value of an attribute of type octet-string.
void	setValue(short value) Set the value of an attribute of type short.
void	setValue(java.lang.String value) Set the value of an attribute of type string.
void	setValue(java.lang.String component, char value) Set the char value of an attribute.
void	setValue(java.lang.String component, int value) Set the long value of an attribute.
void	setValue(java.lang.String component, OctetString value) Set the octet-string value of an attribute.
void	setValue(java.lang.String component, short value) Set the short value of an attribute.
void	setValue(java.lang.String component, java.lang.String value) Set the string value of an attribute.
int	size() Get the number of components in a complex attribute, or elements in an array.
void	size(int n) Resize an array (by adding or deleting elements) so that it contains exactly n elements.
java.lang.String	toString()
java.lang.String	toString(boolean idsOnly)
java.lang.String	toString(boolean idsOnly, boolean brief)

Methods inherited from class java.lang.Object

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

Constructor Detail

Attribute

public Attribute()

Construct an attribute with default values. The set operations must be used to set the values. The type of the attribute is A_NONE, and the operation is NONE.

Attribute

public Attribute(java.lang.String attrName)
          throws java.lang.IllegalArgumentException

Construct an attribute with the specified name, expressed as a string. The set operations must be used to set the values. The type of the attribute is that associated with the registered name in the Attribute Table. The value is empty, and the operation is NONE. Attributes of type COMPLEX contain the complete hierarchy, with all values set to empty.

Parameters:

attrName - The attribute name - e.g. "tt.Date" or "tt.Myclass.tt.Myattr".

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute.

Attribute

public Attribute(java.lang.String attrName,
                 char value)
          throws java.lang.IllegalArgumentException

Construct a char attribute with an initial value.

Parameters:

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or the attribute is not of type char.

Attribute

public Attribute(java.lang.String attrName,
                 int value)
          throws java.lang.IllegalArgumentException

Construct a long attribute with an initial value.

Parameters:

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or the attribute is not of type long.

Attribute

public Attribute(java.lang.String attrName,
                 OctetString value)
          throws java.lang.IllegalArgumentException

Construct an octet-string attribute with an initial value.

Parameters:

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or the attribute is not of type octet-string.

Attribute

public Attribute(java.lang.String attrName,
                 short value)
          throws java.lang.IllegalArgumentException

Construct a short attribute with an initial value.

Parameters:

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or the attribute is not of type short.

Attribute

public Attribute(java.lang.String attrName,
                 java.lang.String value)
          throws java.lang.IllegalArgumentException

Construct a string attribute with an initial value.

Parameters:

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or the attribute is not of type string.

Attribute

public Attribute(java.lang.String className,
                 java.lang.String attrName,
                 char value)
          throws java.lang.IllegalArgumentException

Construct a char attribute with an initial value.

Parameters:

className - The class name of the attribute, expressed as a string - e.g. "tt.Customer".

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or class, or the attribute is not of type char.

Attribute

public Attribute(java.lang.String className,
                 java.lang.String attrName,
                 int value)
          throws java.lang.IllegalArgumentException

Construct a long attribute with an initial value.

Parameters:

className - The class name of the attribute, expressed as a string - e.g. "tt.Customer".

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or class, or the attribute is not of type long.

Attribute

public Attribute(java.lang.String className,
                 java.lang.String attrName,
                 OctetString value)
          throws java.lang.IllegalArgumentException

Construct an octet-string attribute with an initial value.

Parameters:

className - The class name of the attribute, expressed as a string - e.g. "tt.Customer".

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or class, or the attribute is not of type octet-string.

Attribute

public Attribute(java.lang.String className,
                 java.lang.String attrName,
                 short value)
          throws java.lang.IllegalArgumentException

Construct a short attribute with an initial value.

Parameters:

className - The class name of the attribute, expressed as a string - e.g. "tt.Customer".

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or class, or the attribute is not of type short.

Attribute

public Attribute(java.lang.String className,
                 java.lang.String attrName,
                 java.lang.String value)
          throws java.lang.IllegalArgumentException

Construct a string attribute with an initial value.

Parameters:

className - The class name of the attribute, expressed as a string - e.g. "tt.Customer".

attrName - The registered name of the attribute, expressed as a string - e.g. "tt.Date".

value - The initial value.

Throws:

java.lang.IllegalArgumentException - There is no definition for this attribute or class, or the attribute is not of type string.

Method Detail

find

public Attribute find(java.lang.String component)
               throws java.lang.IllegalArgumentException

Parameters:

component - The path to the required attribute. The component is specified either: for complex attributes, as a colon-separated list of dot-separated domain name/attribute name pairs—for example "tt.contact:tt.address : tt.city" (spaces within the specification are ignored); or, for array attributes, as an index, starting from zero. The two notations may be mixed, to traverse a path through both complex and array components—for example "tt.contact : tt.address : 2 : tt.city".

Note: The found component must be of primitive type.

Returns:

The attribute.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

getAttrDomain

public java.lang.String getAttrDomain()

Get the domain name.

Returns:

The domain name.

getAttrFullName

public java.lang.String getAttrFullName()

Get the full attribute name - domain-name.attribute-name.

Returns:

The attribute name.

getAttrName

public java.lang.String getAttrName()

Get the attribute name - without the domain-name.

Returns:

The attribute name.

getAttrOp

public ObjectQ.Operator getAttrOp()

Get the attribute's operation.

Returns:

The operation (REPLACE, ADD_VALUE, ...).

getAttrType

public ObjectQ.AttributeType getAttrType()

Get the attribute's type.

Returns:

The type (A_CHAR, A_SHORT, ...).

getCharValue

public char getCharValue()
                  throws java.lang.IllegalArgumentException

Get the value of an attribute of type char.

Returns:

The value.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

getCharValue

public char getCharValue(java.lang.String component)
                  throws java.lang.IllegalArgumentException,
                         java.lang.IllegalArgumentException

Get the char value associated with an attribute.

Parameters:

component - The path to the attribute.

Returns:

The char value associated with the attribute.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

java.lang.IllegalArgumentException - The attribute is not of type char.

See Also:

find(String)

getClassName

public java.lang.String getClassName()

Get the attribute's classname.

Returns:

The classname.

getLongValue

public int getLongValue()
                 throws java.lang.IllegalArgumentException

Get the value of an attribute of type long (which is really an int).

Returns:

The value.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

getLongValue

public int getLongValue(java.lang.String component)
                 throws java.lang.IllegalArgumentException

Get the long value associated with an attribute (which is really an int).

Parameters:

component - The path to the attribute.

Returns:

The long value associated with the attribute.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found or is not of type long.

See Also:

find(String)

getOctetStringValue

public OctetString getOctetStringValue()
                                throws java.lang.IllegalArgumentException

Get the value of an attribute of type octet-string.

Returns:

The value.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

getOctetStringValue

public OctetString getOctetStringValue(java.lang.String component)
                                throws java.lang.IllegalArgumentException,
                                       java.lang.IllegalArgumentException

Get the octet-string value associated with an attribute.

Parameters:

component - The path to the attribute.

Returns:

The octet-string value associated with the attribute.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

java.lang.IllegalArgumentException - The attribute is not of type octet-string.

See Also:

find(String)

getShortValue

public short getShortValue()
                    throws java.lang.IllegalArgumentException

Get the value of an attribute of type short.

Returns:

The value.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

getShortValue

public short getShortValue(java.lang.String component)
                    throws java.lang.IllegalArgumentException,
                           java.lang.IllegalArgumentException

Get the short value associated with an attribute.

Parameters:

component - The path to the attribute.

Returns:

The short value associated with the attribute.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

java.lang.IllegalArgumentException - The attribute is not of type short.

See Also:

find(String)

getStringValue

public java.lang.String getStringValue()
                                throws java.lang.IllegalArgumentException

Get the value of an attribute of type string.

Returns:

The value.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

getStringValue

public java.lang.String getStringValue(java.lang.String component)
                                throws java.lang.IllegalArgumentException,
                                       java.lang.IllegalArgumentException

Get the string value associated with an attribute.

Parameters:

component - The path to the attribute.

Returns:

The string value associated with the attribute.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

java.lang.IllegalArgumentException - The attribute is not of type string.

See Also:

find(String)

reserve

public void reserve(int n)
             throws java.lang.IllegalArgumentException,
                    java.lang.IllegalArgumentException

Add elements to an array if necessary to ensure that index n is accessible. Elements are only added, and never removed.

Parameters:

n - The index value to be accessed.

Throws:

java.lang.IllegalArgumentException - This isn't an array or the attribute is unrecognised.

restore

public Attribute restore(byte[] bytes,
                         boolean idsOnly)
                  throws java.lang.IllegalArgumentException,
                         BadMagicException

Restore an attribute from a previously flattened byte stream.

Parameters:

bytes - A buffer containing a previously saved attribute.

idsOnly - If true, the buffer contains attribute ids only; otherwise it contains attributes with their associated values.

Returns:

The restored attribute.

Throws:

java.lang.IllegalArgumentException - An attribute was unrecognized or was of the wrong type.

BadMagicException - The "magic number" was invalid.

save

public byte[] save(boolean idsOnly)

Save an attribute or attribute id to a byte stream.

Parameters:

idsOnly - If true, the buffer contains attribute ids only; otherwise it contains attributes with their associated values.

Returns:

The generated byte stream.

setAttrOp

public void setAttrOp(ObjectQ.Operator attrOp)

Set the attribute's operation.

Parameters:

attrOp - The operation (REPLACE, ADD_VALUE, ...).

setValue

public void setValue(char value)
              throws java.lang.IllegalArgumentException

Set the value of an attribute of type char.

Parameters:

value - The value to be set.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

setValue

public void setValue(int value)
              throws java.lang.IllegalArgumentException

Set the value of an attribute of type long.

Parameters:

value - The value to be set.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

setValue

public void setValue(OctetString value)
              throws java.lang.IllegalArgumentException

Set the value of an attribute of type octet-string.

Parameters:

value - The value to be set.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

setValue

public void setValue(short value)
              throws java.lang.IllegalArgumentException

Set the value of an attribute of type short.

Parameters:

value - The value to be set.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

setValue

public void setValue(java.lang.String value)
              throws java.lang.IllegalArgumentException

Set the value of an attribute of type string.

Parameters:

value - The value to be set.

Throws:

java.lang.IllegalArgumentException - The attribute is of the wrong type.

setValue

public void setValue(java.lang.String component,
                     char value)
              throws java.lang.IllegalArgumentException,
                     java.lang.IllegalArgumentException

Set the char value of an attribute.

Parameters:

component - The path to the attribute.

value - The char value.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

java.lang.IllegalArgumentException - The attribute is not of type char.

See Also:

find(String)

setValue

public void setValue(java.lang.String component,
                     int value)
              throws java.lang.IllegalArgumentException,
                     java.lang.IllegalArgumentException

Set the long value of an attribute.

Parameters:

component - The path to the attribute.

value - The long value.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

java.lang.IllegalArgumentException - The attribute is not of type long.

See Also:

find(String)

setValue

public void setValue(java.lang.String component,
                     OctetString value)
              throws java.lang.IllegalArgumentException,
                     java.lang.IllegalArgumentException

Set the octet-string value of an attribute.

Parameters:

component - The path to the attribute.

value - The octet-string value.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

java.lang.IllegalArgumentException - The attribute is not of type octet-string.

See Also:

find(String)

setValue

public void setValue(java.lang.String component,
                     short value)
              throws java.lang.IllegalArgumentException,
                     java.lang.IllegalArgumentException

Set the short value of an attribute.

Parameters:

component - The path to the attribute.

value - The short value.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

java.lang.IllegalArgumentException - The attribute is not of type short.

See Also:

find(String)

setValue

public void setValue(java.lang.String component,
                     java.lang.String value)
              throws java.lang.IllegalArgumentException,
                     java.lang.IllegalArgumentException

Set the string value of an attribute.

Parameters:

component - The path to the attribute.

value - The string value.

Throws:

java.lang.IllegalArgumentException - The attribute can't be found.

java.lang.IllegalArgumentException - The attribute is not of type string.

See Also:

find(String)

size

public int size()

Get the number of components in a complex attribute, or elements in an array.

Returns:

The number of components/elements.

size

public void size(int n)
          throws java.lang.IllegalArgumentException,
                 java.lang.IllegalArgumentException

Resize an array (by adding or deleting elements) so that it contains exactly n elements.

Parameters:

n - The number of elements.

Throws:

java.lang.IllegalArgumentException - This isn't an array.

java.lang.IllegalArgumentException - The attribute is unrecognised.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

toString

public java.lang.String toString(boolean idsOnly)

toString

public java.lang.String toString(boolean idsOnly,
                                 boolean brief)