.. java:import:: java.util Objects

.. java:import:: org.caosdb.server.datatype AbstractDatatype.Table

.. java:import:: org.caosdb.server.entity EntityID

.. java:import:: org.caosdb.server.entity EntityInterface

.. java:import:: org.caosdb.server.entity Message

.. java:import:: org.caosdb.server.utils ServerMessages

.. java:import:: org.jdom2 Element

ReferenceValue
==============

.. java:package:: org.caosdb.server.datatype
   :noindex:

.. java:type:: public class ReferenceValue implements SingleValue

   A ReferenceValue represents the value of a reference property to another entity.

   Differently from other properties, they may be versioned, i.e. they may reference to a specific version of an entity.

   Ways to specify a reference value: {id}@{version} using either the version id (a hex'ed sha256 string) or "HEAD", "HEAD~1", "HEAD~2" and so on. Note: "HEAD" always means the "HEAD" \ *after*\  the transaction. So, if you are changing the referenced entity in the same transaction and you want to reference the entity in the version before the change you need to use "HEAD~1" because that is the old version of the future.

   :author: Timm Fitschen

Constructors
------------
ReferenceValue
^^^^^^^^^^^^^^

.. java:constructor:: public ReferenceValue(EntityInterface entity, boolean versioned)
   :outertype: ReferenceValue

ReferenceValue
^^^^^^^^^^^^^^

.. java:constructor:: public ReferenceValue(EntityID id)
   :outertype: ReferenceValue

ReferenceValue
^^^^^^^^^^^^^^

.. java:constructor:: public ReferenceValue(EntityID id, String version)
   :outertype: ReferenceValue

ReferenceValue
^^^^^^^^^^^^^^

.. java:constructor:: public ReferenceValue(String name)
   :outertype: ReferenceValue

   If the reference is given by name, versioning is not possible (at the moment).

ReferenceValue
^^^^^^^^^^^^^^

.. java:constructor:: public ReferenceValue(String name, String version)
   :outertype: ReferenceValue

Methods
-------
addToElement
^^^^^^^^^^^^

.. java:method:: @Override public void addToElement(Element e)
   :outertype: ReferenceValue

equals
^^^^^^

.. java:method:: @Override public boolean equals(Object obj)
   :outertype: ReferenceValue

equals
^^^^^^

.. java:method:: @Override public boolean equals(Value val)
   :outertype: ReferenceValue

   Test if this is equal to the other object.

   Two references are equal, if 1) they both have IDs and their content is equal or 2) at least one does not have an ID, but their names are equal. Otherwise they are considered unequal.

   :param val: The other object.

getEntity
^^^^^^^^^

.. java:method:: public final EntityInterface getEntity()
   :outertype: ReferenceValue

getId
^^^^^

.. java:method:: public final EntityID getId()
   :outertype: ReferenceValue

getIdVersion
^^^^^^^^^^^^

.. java:method:: public String getIdVersion()
   :outertype: ReferenceValue

getName
^^^^^^^

.. java:method:: public final String getName()
   :outertype: ReferenceValue

getTable
^^^^^^^^

.. java:method:: @Override public Table getTable()
   :outertype: ReferenceValue

getVersion
^^^^^^^^^^

.. java:method:: public final String getVersion()
   :outertype: ReferenceValue

parseFromString
^^^^^^^^^^^^^^^

.. java:method:: public static ReferenceValue parseFromString(String str)
   :outertype: ReferenceValue

   Create a ReferenceValue from a string.

   If the string looks like a valid "entityID@version" string, the result will have the corresponding entity and version parts.

parseIdVersion
^^^^^^^^^^^^^^

.. java:method:: public static ReferenceValue parseIdVersion(String str)
   :outertype: ReferenceValue

   Split a reference string into an entity part and a version part, if there is a version part.

   If parsing the entity ID part to an integer fails, a NumberFormatException may be thrown.

parseReference
^^^^^^^^^^^^^^

.. java:method:: public static ReferenceValue parseReference(EntityID reference)
   :outertype: ReferenceValue

parseReference
^^^^^^^^^^^^^^

.. java:method:: public static ReferenceValue parseReference(Object reference) throws Message
   :outertype: ReferenceValue

setEntity
^^^^^^^^^

.. java:method:: public final void setEntity(EntityInterface entity, boolean versioned)
   :outertype: ReferenceValue

setId
^^^^^

.. java:method:: public final void setId(EntityID id)
   :outertype: ReferenceValue

setName
^^^^^^^

.. java:method:: public void setName(String name)
   :outertype: ReferenceValue

toDatabaseString
^^^^^^^^^^^^^^^^

.. java:method:: @Override public String toDatabaseString()
   :outertype: ReferenceValue

toString
^^^^^^^^

.. java:method:: @Override public String toString()
   :outertype: ReferenceValue

   Produce a nice but short string:

   Case 1 "versioned" (reference to an entity without specifying that entity's version): Produces a string like "1234" or "Experiment". Note that referencing via name is never versioned.

   Case 2 "unversioned" (reference to an entity with a specified version): Produces a string like "1234@ab987f".