public interface ChannelAccessString extends ChannelAccessGettableValue<java.lang.String>
Channel Access value that stores strings.
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 |
---|---|
ChannelAccessString |
asReadOnlyValue()
Returns a read-only version of this value.
|
ChannelAccessString |
clone()
Creates and returns a copy of this object.
|
java.nio.charset.Charset |
getCharset()
Returns the encoding that is used for converting Java
strings into raw (null-terminated) strings and vice-versa.
|
byte[] |
getRawValue()
Returns the raw representation of the strings.
|
java.util.List<java.lang.String> |
getValue()
Returns the list storing the actual value elements.
|
void |
setRawValue(byte[] rawValue)
Updates the string values using the specified raw representations.
|
void |
setValue(java.util.Collection<java.lang.String> value)
Replaces this value's elements with the elements from the specified
collection.
|
equals, getGenericValueElement, getType, getValueSize, hashCode, isReadOnly, iterator, toString
java.util.List<java.lang.String> getValue()
Returns the list storing the actual value elements. The list is returned by reference, so subsequent changes to the list will affect this value and vice-versa. Therefore, the list may not be modified after this value has been passed to a different component. If this value is read-only, the list returned is also read-only.
The list returned does not allow the insertion of null
elements.
null
).
Elements of the list are never null
.ChannelAccessValue.getValueSize()
void setValue(java.util.Collection<java.lang.String> value)
Replaces this value's elements with the elements from the specified
collection. This has the same effect as calling clear()
followed by addAll(value)
on the list returned by
getValue()
.
The string's raw representation is updated automatically. Strings that are truncated while being converted to their raw representation still maintain their original length in the list of element strings.
value
- collection of strings that should replace this value's
elements.java.lang.NullPointerException
- if value
is null
or contains
null
elements.java.lang.UnsupportedOperationException
- if this value is read-only (ChannelAccessValue.isReadOnly()
returns
true
).byte[] getRawValue()
Returns the raw representation of the strings. This an array of N * 40
bytes, where N is the number of strings (as returned by
ChannelAccessValue.getValueSize()
). Each string in this array has exactly 40 bytes
and is null-terminated. This means that the string with the zero-based
index i starts at an array index of i * 40.
The array returned is a copy, so modifications to it will not affect this value.
null
).getValue()
,
ChannelAccessValue.getValueSize()
,
getCharset()
void setRawValue(byte[] rawValue)
Updates the string values using the specified raw representations. The size of the array passed must be an integer multiple of 40. Each sequence of 40 bytes is interpreted as one null-terminated string. The strings must be null-terminated, therefore the size of an individual string must not exceed 39 characters (not including the terminating null-byte).
The array is copied, thus subsequent modifications of the array will not
affect this value. The Java strings
returned by
getValue()
are updated by converting the specified raw strings
using the specified encoding
.
rawValue
- new raw representation of the strings (never null
). The size of the array must be a multiple of 40 and strings
must be null terminated.java.lang.IllegalArgumentException
- if the size of the array is not an integer multiple of 40 or
the individual strings are not null terminated.java.lang.UnsupportedOperationException
- if this value is read-only (ChannelAccessValue.isReadOnly()
returns
true
).java.nio.charset.Charset getCharset()
null
).ChannelAccessString 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.
asReadOnlyValue
in interface ChannelAccessGettableValue<java.lang.String>
asReadOnlyValue
in interface ChannelAccessValue<java.lang.String>
null
).ChannelAccessString 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.
clone
in interface ChannelAccessGettableValue<java.lang.String>
clone
in interface ChannelAccessValue<java.lang.String>
Copyright © 2014–2018 aquenos GmbH. All rights reserved.