|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Label
A set of attributes that can be used to decorate a node or
an arc of a graph. Attributes appear in the form of <key,value>
pairs, where keys are of type String
. Among attributes,
one (called the well-known attribute), has a special status:
its key can be obtained by using the wellKnownAttributeKey()
method.
Values associated to attributes can be anything: the value can be
obtained (in the form of an object) with get(String)
.
If the value is of primitive type, the alternative type-specific method
(e.g., getInt(String)
, or getChar(String)
) can be
called, with the proviso that such methods may throw an IllegalArgumentException
if the attribute type can not be converted to the one specified without loss of information.
The value of the well-known attribute can be obtained with get()
,
or with the appropriate type-specific version of the method.
Implementations must provide toBitStream(OutputBitStream, int)
and fromBitStream(InputBitStream, int)
methods that serialise to a bitstream and deserialise to a bitstream a label, respectively. Since
fromBitStream(InputBitStream, int)
has no length information, the label format must
be self-delimiting. This can be obtained with a fixed length scheme (see, e.g., FixedWidthIntLabel
),
or using self-delimiting codes (see, e.g., GammaCodedIntLabel
).
The methods toBitStream(OutputBitStream,int)
and fromBitStream(InputBitStream,int)
are given as an additional information the number of source
node of the arc over which this label is put. They may use this information to decide how the
label should be stored (typically, to do a more clever compression job).
The advantage of fixed-width labels (i.e., those for which fixedWidth()
does not return -1)
is that when loading a BitStreamArcLabelledImmutableGraph
with an offset step larger than 1 the position in the bitstream
for the labels of a node can be calculated more quickly, as the computation just requires the outdegree
of the nodes, whereas in general one has to skip in-between labels with an explicit deserialisation.
By convention, all concrete classes implementing this interface must follow the ObjectParser
conventions:
in particular, they must provide a constructor accepting strings (either in fixed or variable number) where the first string is the key.
The constructor must perform data validation and build an instance with a default value (e.g., 0 for numerical labels). The
constructor is used, for instance, by BitStreamArcLabelledImmutableGraph
to instantiate a label prototype.
Finally, the method toSpec()
must return a string that is accepted by ObjectParser
.
Method Summary | |
---|---|
String[] |
attributeKeys()
All attribute keys (in arbitrary order). |
Class<?>[] |
attributeTypes()
The types of all attributes in the same order as they are returned by attributeKeys() . |
Label |
copy()
Returns a copy of this label. |
int |
fixedWidth()
Returns the fixed length of this label, in bits, if this label has fixed width. |
int |
fromBitStream(InputBitStream inputBitStream,
int source)
Fills this label with data from the given input bit stream, knowing the source node of the arc. |
Object |
get()
The value associated to the well-known attribute. |
Object |
get(String key)
The value associated to the attribute with given key. |
boolean |
getBoolean()
The value associated to the well-known attribute, provided that the latter has a type that fits a boolean. |
boolean |
getBoolean(String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a boolean. |
byte |
getByte()
The value associated to the well-known attribute, provided that the latter has a type that fits a byte. |
byte |
getByte(String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a byte. |
char |
getChar()
The value associated to the well-known attribute, provided that the latter has a type that fits a char. |
char |
getChar(String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a char. |
double |
getDouble()
The value associated to the well-known attribute, provided that the latter has a type that fits a double. |
double |
getDouble(String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a double. |
float |
getFloat()
The value associated to the well-known attribute, provided that the latter has a type that fits a float. |
float |
getFloat(String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a float. |
int |
getInt()
The value associated to the well-known attribute, provided that the latter has a type that fits a int. |
int |
getInt(String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a int. |
long |
getLong()
The value associated to the well-known attribute, provided that the latter has a type that fits a long. |
long |
getLong(String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a long. |
short |
getShort()
The value associated to the well-known attribute, provided that the latter has a type that fits a short. |
short |
getShort(String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a short. |
int |
toBitStream(OutputBitStream outputBitStream,
int source)
Writes out this label to the given input bit stream, in self-delimiting form, knowing the source node of the arc. |
String |
toSpec()
Returns a string representing the specification of this label. |
String |
wellKnownAttributeKey()
Returns the well-known attribute key. |
Method Detail |
---|
String wellKnownAttributeKey()
String[] attributeKeys()
Class<?>[] attributeTypes()
attributeKeys()
.
Object get(String key) throws NoSuchElementException
key
- the attribute key.
NoSuchElementException
- if the attribute key is not one of the attributes of this label.byte getByte(String key) throws IllegalArgumentException
IllegalArgumentException
is thrown.
key
- the attribute key.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.short getShort(String key) throws IllegalArgumentException
IllegalArgumentException
is thrown.
key
- the attribute key.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.int getInt(String key) throws IllegalArgumentException
IllegalArgumentException
is thrown.
key
- the attribute key.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.long getLong(String key) throws IllegalArgumentException
IllegalArgumentException
is thrown.
key
- the attribute key.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.float getFloat(String key) throws IllegalArgumentException
IllegalArgumentException
is thrown.
key
- the attribute key.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.double getDouble(String key) throws IllegalArgumentException
IllegalArgumentException
is thrown.
key
- the attribute key.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.char getChar(String key) throws IllegalArgumentException
IllegalArgumentException
is thrown.
key
- the attribute key.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.boolean getBoolean(String key) throws IllegalArgumentException
IllegalArgumentException
is thrown.
key
- the attribute key.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.Object get() throws NoSuchElementException
NoSuchElementException
byte getByte() throws IllegalArgumentException
IllegalArgumentException
is thrown.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.short getShort() throws IllegalArgumentException
IllegalArgumentException
is thrown.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.int getInt() throws IllegalArgumentException
IllegalArgumentException
is thrown.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.long getLong() throws IllegalArgumentException
IllegalArgumentException
is thrown.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.float getFloat() throws IllegalArgumentException
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.double getDouble() throws IllegalArgumentException
IllegalArgumentException
is thrown.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.char getChar() throws IllegalArgumentException
IllegalArgumentException
is thrown.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.boolean getBoolean() throws IllegalArgumentException
IllegalArgumentException
is thrown.
IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.Label copy()
copy
in interface FlyweightPrototype<Label>
String toSpec()
Each label class can be instantiated in several ways (e.g., FixedWidthIntLabel
requires a name for the well-known attribute and a number of bits). This method must return
a representation that can be used by ObjectParser
to instantiate the class, and
consequently there must exist a matching constructor whose arguments are strings.
There is an equation that must be always satisfied:
ObjectParser.fromSpec( x.toSpec() ).toSpec().equals( x.toSpec() )
ObjectParser.fromSpec(String, Class)
int fromBitStream(InputBitStream inputBitStream, int source) throws IOException, UnsupportedOperationException
fixedWidth()
is not negative, the value returned must coincide with fixedWidth()
.
This method is optional.
inputBitStream
- an input bit stream offering a label.source
- the source node.
IOException
UnsupportedOperationException
int toBitStream(OutputBitStream outputBitStream, int source) throws IOException, UnsupportedOperationException
fixedWidth()
is not negative, the value returned must coincide with fixedWidth()
.
This method is optional.
outputBitStream
- an output bit stream where the label will be written.source
- the source node.
IOException
UnsupportedOperationException
int fixedWidth()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |