Package it.unimi.dsi.webgraph.labelling

Interface Label

All Superinterfaces:
FlyweightPrototype<Label>
All Known Implementing Classes:
AbstractIntLabel, AbstractIntListLabel, AbstractLabel, FixedWidthIntLabel, FixedWidthIntListLabel, GammaCodedIntLabel
public interface Label
extends FlyweightPrototype<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.

Serialisation

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.

String-based constructors

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.

  • Field Summary

    Fields
    Modifier and Type Field Description
    static Label[] EMPTY_LABEL_ARRAY  

  • Method Summary

    Modifier and Type Method Description
    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.

  • Field Details

    • EMPTY_LABEL_ARRAY

      static final Label[] EMPTY_LABEL_ARRAY

  • Method Details

    • wellKnownAttributeKey

      String wellKnownAttributeKey()
      Returns the well-known attribute key.
      Returns:
      the well-known attribute key.

    • attributeKeys

      String[] attributeKeys()
      All attribute keys (in arbitrary order).
      Returns:
      the keys of all attributes.

    • attributeTypes

      Class<?>[] attributeTypes()
      The types of all attributes in the same order as they are returned by attributeKeys().
      Returns:
      the type of all attributes.

    • get

      Object get​(String key) throws NoSuchElementException
      The value associated to the attribute with given key.
      Parameters:
      key - the attribute key.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      NoSuchElementException - if the attribute key is not one of the attributes of this label.

    • getByte

      byte getByte​(String key) throws IllegalArgumentException
      The value associated to the attribute with given key, provided that the latter has a type that fits a byte. Otherwise, an IllegalArgumentException is thrown.
      Parameters:
      key - the attribute key.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getShort

      short getShort​(String key) throws IllegalArgumentException
      The value associated to the attribute with given key, provided that the latter has a type that fits a short. Otherwise, an IllegalArgumentException is thrown.
      Parameters:
      key - the attribute key.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getInt

      int getInt​(String key) throws IllegalArgumentException
      The value associated to the attribute with given key, provided that the latter has a type that fits a int. Otherwise, an IllegalArgumentException is thrown.
      Parameters:
      key - the attribute key.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getLong

      long getLong​(String key) throws IllegalArgumentException
      The value associated to the attribute with given key, provided that the latter has a type that fits a long. Otherwise, an IllegalArgumentException is thrown.
      Parameters:
      key - the attribute key.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getFloat

      float getFloat​(String key) throws IllegalArgumentException
      The value associated to the attribute with given key, provided that the latter has a type that fits a float. Otherwise, an IllegalArgumentException is thrown.
      Parameters:
      key - the attribute key.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getDouble

      double getDouble​(String key) throws IllegalArgumentException
      The value associated to the attribute with given key, provided that the latter has a type that fits a double. Otherwise, an IllegalArgumentException is thrown.
      Parameters:
      key - the attribute key.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getChar

      char getChar​(String key) throws IllegalArgumentException
      The value associated to the attribute with given key, provided that the latter has a type that fits a char. Otherwise, an IllegalArgumentException is thrown.
      Parameters:
      key - the attribute key.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getBoolean

      boolean getBoolean​(String key) throws IllegalArgumentException
      The value associated to the attribute with given key, provided that the latter has a type that fits a boolean. Otherwise, an IllegalArgumentException is thrown.
      Parameters:
      key - the attribute key.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • get

      Object get() throws NoSuchElementException
      The value associated to the well-known attribute.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      NoSuchElementException

    • getByte

      byte getByte() throws IllegalArgumentException
      The value associated to the well-known attribute, provided that the latter has a type that fits a byte. Otherwise, an IllegalArgumentException is thrown.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getShort

      short getShort() throws IllegalArgumentException
      The value associated to the well-known attribute, provided that the latter has a type that fits a short. Otherwise, an IllegalArgumentException is thrown.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getInt

      int getInt() throws IllegalArgumentException
      The value associated to the well-known attribute, provided that the latter has a type that fits a int. Otherwise, an IllegalArgumentException is thrown.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getLong

      long getLong() throws IllegalArgumentException
      The value associated to the well-known attribute, provided that the latter has a type that fits a long. Otherwise, an IllegalArgumentException is thrown.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getFloat

      float getFloat() throws IllegalArgumentException
      The value associated to the well-known attribute, provided that the latter has a type that fits a float.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getDouble

      double getDouble() throws IllegalArgumentException
      The value associated to the well-known attribute, provided that the latter has a type that fits a double. Otherwise, an IllegalArgumentException is thrown.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getChar

      char getChar() throws IllegalArgumentException
      The value associated to the well-known attribute, provided that the latter has a type that fits a char. Otherwise, an IllegalArgumentException is thrown.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • getBoolean

      boolean getBoolean() throws IllegalArgumentException
      The value associated to the well-known attribute, provided that the latter has a type that fits a boolean. Otherwise, an IllegalArgumentException is thrown.
      Returns:
      the attribute value; if the attribute type is primitive, it is wrapped suitably.
      Throws:
      IllegalArgumentException - if the attribute key is not known, or it has the wrong type.

    • copy

      Label copy()
      Returns a copy of this label.
      Specified by:
      copy in interface FlyweightPrototype<Label>
      Returns:
      a new label that copies this one.

    • toSpec

      String toSpec()
      Returns a string representing the specification of this label.

      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())
      Returns:
      a string representing the specification of this label.
      See Also:
      ObjectParser.fromSpec(String, Class)

    • fromBitStream

      int fromBitStream​(InputBitStream inputBitStream, int source) throws IOException, UnsupportedOperationException
      Fills this label with data from the given input bit stream, knowing the source node of the arc. If fixedWidth() is not negative, the value returned must coincide with fixedWidth(). This method is optional.
      Parameters:
      inputBitStream - an input bit stream offering a label.
      source - the source node.
      Returns:
      the number of bits read to fill this label.
      Throws:
      IOException
      UnsupportedOperationException

    • toBitStream

      int toBitStream​(OutputBitStream outputBitStream, int source) throws IOException, UnsupportedOperationException
      Writes out this label to the given input bit stream, in self-delimiting form, knowing the source node of the arc. If fixedWidth() is not negative, the value returned must coincide with fixedWidth(). This method is optional.
      Parameters:
      outputBitStream - an output bit stream where the label will be written.
      source - the source node.
      Returns:
      the number of bits written.
      Throws:
      IOException
      UnsupportedOperationException

    • fixedWidth

      int fixedWidth()
      Returns the fixed length of this label, in bits, if this label has fixed width.
      Returns:
      the fixed length of this label, or -1 if this label has not fixed width.