ElementType
- type of the actual value elements. For primitives, this is the
boxed variant.public interface ChannelAccessValue<ElementType>
extends java.lang.Cloneable, java.lang.Iterable<ElementType>
Channel Access value. This interface is the base interface for all values that can be transferred via the Channel Access protocol.
Objects implementing this interface can be expected to have implementations
of equals(Object)
and hashCode()
that do not simply check for object identity but actually compare
the object's internal state. All objects of this type can be cloned.
Objects implementing this interface can be expected to be safe for concurrent access by multiple threads as long as none of these threads modifies the object. Modifications to the object have to be synchronized by establishing an external mutex.
A read-only version of a value can be retrieved through the
asReadOnlyValue()
. Such a version shares it data with the read-write
variant that it has been created from as is suitable to be passed to other
components that shall not modify the value. Modifications to the original
value however will also affect the read-only variants, so typically, code
that creates a read-only variant should not keep references to the read-write
variant or ensure that it does not modify the read-write variant while other
threads are accessing the read-only variant.
All objects that implement this interface can be cloned. Cloning an instance always yields a read-write value, even if cloning a read-only value. The cloned instance is completely independent of its origin, so it can safely be modified without affecting the value it was cloned from.
Channel Access values can be created using ChannelAccessValueFactory
or can be deserialized from their serialized representation using
ChannelAccessValueCodec
.
This interface should not be implemented by user-defined classes. Code that
wants to create an instance implementing this interface should use the
methods provided by ChannelAccessValueFactory
instead.
Modifier and Type | Method and Description |
---|---|
ChannelAccessValue<ElementType> |
asReadOnlyValue()
Returns a read-only version of this value.
|
ChannelAccessValue<ElementType> |
clone()
Creates and returns a copy of this object.
|
boolean |
equals(java.lang.Object obj)
Tells whether the specified object represents the same Channel Access
value.
|
ElementType |
getGenericValueElement(int index)
Returns the value element with the specified index.
|
ChannelAccessValueType |
getType()
Returns the identifier for this value's underlying type.
|
int |
getValueSize()
Returns the number of elements this value has.
|
int |
hashCode()
Returns a hash code value for this Channel Access value.
|
boolean |
isReadOnly()
Returns whether this value is read-only.
|
java.util.ListIterator<ElementType> |
iterator()
Returns a (read-only) iterator that iterates over the actual value
elements.
|
java.lang.String |
toString()
Returns a string representation of this Channel Access value.
|
ChannelAccessValueType getType()
null
).int getValueSize()
getGenericValueElement(int)
, this method can be used to iterate
over the elements, as an alternative to the iterator()
method.getGenericValueElement(int)
ElementType getGenericValueElement(int index)
Returns the value element with the specified index.
Code that wants to get elements should prefer to use the
getValue()
method in the respective child class and access
the array through the methods provided by the buffer object for better
performance (avoiding boxing and unboxing of primitives). This method is
only provided for code that has to deal with values in a generic way
(without knowing the exact type of the actual value).
index
- zero-based index into the element array.null
).java.lang.IndexOutOfBoundsException
- if the index is equal to or greater than the
size of the element array
. .java.util.ListIterator<ElementType> iterator()
iterator
in interface java.lang.Iterable<ElementType>
ChannelAccessValue<ElementType> asReadOnlyValue()
Returns a read-only version of this value. If the value is read-only, this value is returned. Otherwise, a wrapped version of this value, that does not allow modifications is returned.
Please note that the read-only value is not a copy of this value, but just a wrapper around it. This means, that modifications of the wrapped value will result in modifications of the read-only value. Therefore it is bad practice to modify a value that has been used as the base for a read-only value, because code that still has a reference to the read-only value might not expect this change and thus fail unexpectedly.
null
).boolean isReadOnly()
OperationNotSupportedException
.true
if this value is read-only, false
if it may be modified.int hashCode()
Returns a hash code value for this Channel Access value. This method is supported for the benefit of hash tables. Typically, the hash code is calculated as a combination of the hash codes of the elements and meta-data included in this value object. However, the concrete algorithm is up to the implementing class.
If two Channel Access values are equal (as indicated by the return value
of equals(Object)
), they also have the same hash code. However,
the fact that two values have the same hash code does not imply that they
are equal. This contract must be honored by all implementations of this
method.
hashCode
in class java.lang.Object
boolean equals(java.lang.Object obj)
Tells whether the specified object represents the same Channel Access value.
Two values are considered equal if they are of the same type and have the same elements and meta-data (if the type contains meta-data).
equals
in class java.lang.Object
obj
- reference object with which this object is compared.true
if obj
is a Channel Access Value
that is of the same type and has the elements and meta-data as
this value, false
otherwise.ChannelAccessValue<ElementType> clone()
Creates and returns a copy of this object. The object returned is completely independent from this object. This means that modifications to this object will not affect the returned object and vice-versa.
The object returned is guaranteed to be completely identical to this
object, including its type. This means that
x.clone().equals(x)
and
x.clone().getClass() == x.getClass()
are always
true
.
The returned value is guaranteed to allow write access, even if this value is read-only. This means that cloning a read-only value is a good way to get a writable copy.
java.lang.String toString()
toString
in class java.lang.Object
Copyright © 2014–2017 aquenos GmbH. All rights reserved.