public class DOFString extends java.lang.Object implements DOFValue
DOFValue
that supports strings and encoded strings.
NOTE: Typically applications need not be concerned with encodings. The library will automatically
convert DOFString values to the encoding required by a DOF Interface. The exception to this is
when the application deals directly with byte arrays. In that case, knowledge of the the encoding is
necessary in order to correctly convert the byte array to a string value.DOFString.Type
,
Serialized FormModifier and Type | Class and Description |
---|---|
static class |
DOFString.Type
|
Modifier and Type | Field and Description |
---|---|
static int |
US_ASCII
This is the MIB enum entry for US ASCII strings.
|
static int |
UTF_8
This is the MIB enum entry for UTF-8 strings.
|
Constructor and Description |
---|
DOFString(DOFString.Type pattern,
DOFPacket packet)
Create a DOFString instance from serial form.
|
DOFString(DOFString.Type type,
java.lang.String data)
Create a string value, specifying the type.
|
DOFString(short encoding,
int length,
byte[] data)
Create a string value from a byte array.
|
DOFString(java.lang.String data)
Create a string value using UTF_8 encoding.
|
Modifier and Type | Method and Description |
---|---|
static DOFString[] |
array(java.util.List<java.lang.String> data)
Convert a list of Java Strings into an array of DOFString.
|
static DOFString[] |
array(java.lang.String[] data)
Convert an array of java Strings into an array of DOFStrings.
|
boolean |
equals(java.lang.Object object)
Return whether two values are equal.
|
java.lang.String |
get()
Return the value of the string.
|
byte[] |
getBuffer()
Return the encoded buffer of the string.
|
DOFType |
getDOFType()
Return the
DOFType of the value. |
int |
hashCode()
Return a hash code for the object.
|
void |
isCompatibleWith(DOFType type)
Verify that a value is compatible with the specified
DOFType . |
void |
marshal(DOFType type,
DOFPacket packet)
Write a value to a
DOFPacket . |
java.lang.String |
toString()
Returns a representation of the value.
|
public static final int US_ASCII
public static final int UTF_8
public DOFString(java.lang.String data)
data
- The data to encapsulate. Must not be null.public DOFString(DOFString.Type type, java.lang.String data)
type
- The type of the string. Must not be null.data
- The data to encapsulate. Must not be null.public DOFString(short encoding, int length, byte[] data)
encoding
- The MIB enum from http://www.iana.org/assignments/character-sets.length
- The character length (not necessarily the length of the array -- depends upon the encoding). This is used for type-checking.data
- The buffer containing encoded data.public DOFString(DOFString.Type pattern, DOFPacket packet) throws DOFMarshalException
pattern
- The type of the variable. Must not be null.packet
- The buffer which contains the serialized form of the object. Must not be null.DOFMarshalException
- If there are errors in the data or the buffer. This is an exception to the rule that
non-RuntimeExceptions not be thrown from a constructor.Marshallable
public java.lang.String get()
null
if the encoding
of the string is unknown, in which case the getBuffer()
method will return
the encoded buffer and the DOFType.getEncoding()
on the value's type will
return the encoding used.null
.public byte[] getBuffer()
null
if the encoding
of the string is unknown, in which case the get()
method will return the
string value.null
public DOFType getDOFType()
DOFValue
DOFType
of the value.
The type returned must be the one that is related directly
to this value implementation. In other words, calling DOFType.getInstance(org.opendof.core.oal.DOFPacket)
on that type
must return the same class as this value.
Note that queries made against the type of the value do not represent the specific details
of the value itself, rather they represent the capabilities of the value. For example, asking
the type what a type's maximum length is by using DOFType.getMaxLength()
does not indicate
anything about the actual length of a given value - even if that value returned the type using this call.
This allows a common DOFType
implementation to be associated with many different values.getDOFType
in interface DOFValue
public void isCompatibleWith(DOFType type) throws DOFErrorException
DOFValue
DOFType
.
Compatibility is less strict of a requirement that saying that the type of the value is
equal to the given type. Instead, compatibility is verified by introspecting the value
and the type, and checking whether or not they are compatible.
A simple example of this is a string value that has a length of 25 characters. The type
associated with the value (as returned by DOFValue.getDOFType()
) may have a maximum length of
50 characters. The type passed to this routine may have a maximum length of 30 characters
as indicated by DOFType.getMaxLength()
. In this case the value would be compatible,
even though the value's type is not compatible with the passed type as the maximum lengths
are not compatible. It is the actual data length (25 characters) that matters for this
routine.
The following must always succeed without an exception:
value.CompatibleWith( value.getDOFType() )
In other words, a value must always be compatible with its own type.isCompatibleWith
in interface DOFValue
type
- The type to compare against. The type must be reflected in order
to determine equivalence, although equality of the argument with the type of the value
ensures compatibility.DOFErrorException
- The value is not compatible.public void marshal(DOFType type, DOFPacket packet) throws DOFMarshalException, DOFErrorException
DOFValue
DOFPacket
.
This is an advanced routine and requires knowledge of the DOF Protocol Specification
in order to ensure that the value written to the buffer follows the specification requirements for
the value's type. Note that even "custom" types are built using DOF core types, and so the
buffered format for all values is determined by the specification.
NOTE: Values are written from back to front. In other words, the first item written to the packet
will be the last item in the packet.
Finally, implements must ensure that the value (data) cannot change during this call.
This means that unless the implementation
is immutable it should lock itself for the duration of this call. Once this call is
complete then the value may be changed without affecting the value written to the packet.
Note that the library has likely already done a compatibility check between the value and the
type, and so the check should not be made again (for performance reasons). However, in the case
that the check has not been done, it is possible that this method will encounter various
failures due to type casting. These should be caught and returned as a DOFErrorException
.marshal
in interface DOFValue
type
- The type that must be written. This type determines the wire formatting of the value.packet
- The destination packet.DOFMarshalException
- The value cannot be written.DOFErrorException
- There were problems between the type and the value.public static DOFString[] array(java.lang.String[] data)
data
- The data to encapsulate. Must not be null.getDOFType()
public static DOFString[] array(java.util.List<java.lang.String> data)
data
- The data to encapsulate. Must not be null.getDOFType()
public boolean equals(java.lang.Object object)
DOFValue
public int hashCode()
DOFValue
DOFValue.equals(java.lang.Object)
returns true
.public java.lang.String toString()
DOFValue