public abstract class Datum extends java.lang.Object implements java.io.Serializable, java.lang.Comparable<Datum>
An instance of this class represents a data value that can be the object of a triple. It can be an item, or it can be a boolean, an integer, a real number, a piece of text, or a sequence of binary digits.
A datum contains the type of the value and a summary of the value. For some binary and text datums that are objects of triples, the value itself cannot be obtained from the datum and must be retrieved from the source holding the triple. For other binary and text datums, and for item, boolean, integer, and real number triples, the value can be obtained from the datum.
Modifier and Type | Class and Description |
---|---|
static class |
Datum.Type
The possible types that a datum can have
|
Constructor and Description |
---|
Datum() |
Modifier and Type | Method and Description |
---|---|
int |
compareTo(Datum d)
Compare to another datum.
|
static Datum |
create(boolean b)
Create a BOOLEAN datum
|
static Datum |
create(java.lang.Double d)
Create a REAL datum whose value is supplied as a
double-precision 64-bit IEEE 754 floating point number
|
static Datum |
create(float f)
Create a REAL datum whose value is supplied as a
single-precision 32-bit IEEE 754 floating point number
|
static Datum |
create(int i)
Create an INTEGRAL datum whose value is supplied as a
32-bit signed two's complement integer
|
static Datum |
create(Item item)
Create an ITEM datum, given an item
|
static Datum |
create(long l)
Create an INTEGRAL datum whose value is supplied as a
64-bit two's complement integer
|
static Datum |
create(long sourceNr,
long itemNr)
Create an ITEM datum, given the identification of an item
|
static Datum |
create(short s)
Create an INTEGRAL datum whose value is supplied as a
16-bit signed two's complement integer
|
static Datum |
createBinary(byte[] bytes)
Create a BINARY datum, given a byte array
|
static Datum |
createBinary(java.io.File file)
Create a BINARY datum, given a binary file
|
static Datum |
createBinary(long sourceNr,
long tripleNr,
long summaryValue)
Create a BINARY datum, given the identification of a triple
with a binary object.
|
static Datum |
createText(java.io.File file)
Create a TEXT datum, given a text file
|
static Datum |
createText(long sourceNr,
long tripleNr,
long summaryValue)
Create a TEXT datum, given the identification of a triple
with a text object.
|
static Datum |
createText(java.lang.String string)
Create a TEXT datum, given a string
|
boolean |
equals(java.lang.Object obj) |
byte[] |
getBinaryValueAsArray()
Get the value of the datum as a byte array
if it is a BINARY object
|
java.lang.String |
getBinaryValueForDisplay()
Get the value of the datum as a string for display
if its is a BINARY object
|
java.io.BufferedInputStream |
getBinaryValueStream()
Get an InputStream to read the value of the datum if
it is a BINARY object
|
boolean |
getBooleanValue()
Get the value of a datum if this is a BOOLEAN,
or throw an exception if it is not.
|
static boolean |
getBooleanValueFromSummary(long summary)
Get a boolean value from its summary
|
static byte[] |
getBytesFromStream(java.io.BufferedInputStream stream)
Read a stream into a byte array
|
static java.lang.String |
getByteString(byte[] bytes)
Get a text representation of a byte array
|
long |
getIntegralValue()
Get the value of a datum if this is an INTEGRAL,
or throw an exception if it is not.
|
static long |
getIntegralValueFromSummary(long summary)
Get an integral value from its summary
|
Item |
getItemValue()
Get the value of the datum if this is an ITEM,
or throw an exception if it is not.
|
abstract int |
getLength()
Get the length of the value, expressed in the
units of the value's type (bytes for BINARY,
characters for TEXT).
|
double |
getRealValue()
Get the value of a datum if this is a REAL,
or throw an exception if it is not.
|
static double |
getRealValueFromSummary(long summary)
Get a real number value from its summary
|
static long |
getSummary(boolean b)
Get the summary of a boolean value.
|
static long |
getSummary(double real)
Get the summary of a real value.
|
static long |
getSummary(Item item)
Get the summary of an item value.
|
static long |
getSummary(long integral)
Get the summary of an integral value.
|
long |
getSummaryValue()
Get the summary value of the datum
|
java.lang.String |
getTextValueAsString()
Get the value of the datum as a String if
it is a TEXT object, or throw an exception if it is not.
|
java.lang.String |
getTextValueForDisplay()
Get the value of the datum as a string for display
if it is a TEXT object, or throw an exception if it is not.
|
java.io.BufferedReader |
getTextValueReader()
Get a Reader to read the value of the datum if
it is a TEXT object, or throw an exception if it is not.
|
Datum.Type |
getType()
Get the type of the datum
|
int |
hashCode() |
boolean |
heldInSource()
Determine whether the value needs to be retrieved from the
source of a triple
|
static int |
lengthComponent(long summary)
Get the length of a text or binary object from
its summary value.
|
int |
lexicalCompareTo(Datum d)
Compare the datum with another datum.
|
static byte[] |
parseByteString(java.lang.String s)
Parse a text representation of a sequence of bytes
|
abstract java.lang.String |
print()
Get a text representation of the value of the
datum suitable for display
|
void |
setSummaryValue(java.lang.Long value)
Set the summary value of the datum
|
abstract java.lang.String |
simpleTextRepresentation()
Get a simple text representation of the datum suitable
for display.
|
org.json.simple.JSONObject |
toJsonObject()
Get a JSON object that represents the datum
|
java.lang.String |
toString() |
static long |
updateSummary(long summary,
byte[] buf)
Update the summary of a sequence of bytes when more bytes
are added to it from a byte array.
|
static long |
updateSummary(long summary,
byte[] buf,
int length)
Update the summary of a sequence of bytes when more bytes
are added to it from part of a byte array.
|
static long |
updateSummary(long summary,
java.nio.ByteBuffer buf)
Update the summary of a sequence of bytes when more bytes
are added to it from a ByteBuffer.
|
static long |
updateSummary(long summary,
char c)
Update the summary of a piece of text when a character is
added to it.
|
static long |
updateSummary(long summary,
char[] buf)
Update the summary of a piece of text when more characters
are added to it from a character array.
|
static long |
updateSummary(long summary,
char[] buf,
int length)
Update the summary of a piece of text when more characters
are added to it from part of an array.
|
static long |
updateSummary(long summary,
java.lang.String string)
Update the summary of a piece of text when a text string is
added to it.
|
abstract boolean |
valueShouldBeRead()
Determine whether it is better to read the value
of this datum rather than obtaining it as a
String or byte array.
|
public Datum.Type getType()
public long getSummaryValue()
public void setSummaryValue(java.lang.Long value)
value
- the summary value to be setpublic boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object
public static Datum create(Item item)
item
- the value of the datumpublic static Datum create(long sourceNr, long itemNr)
sourceNr
- the numeric identifier of the source of the
value of the datumitemNr
- the numeric identifier of the value of the datum
in its sourcepublic static Datum create(boolean b)
b
- the boolean value of the datumpublic static Datum create(short s)
s
- the integer value of the datumpublic static Datum create(int i)
i
- the integer value of the datumpublic static Datum create(long l)
l
- the integer value of the datumpublic static Datum create(float f)
f
- the real number value of the datumpublic static Datum create(java.lang.Double d)
d
- the real number value of the datumpublic static Datum createText(java.lang.String string) throws TripleStoreNonFatalException
string
- the value of the datumTripleStoreNonFatalException
public static Datum createText(java.io.File file) throws TripleStoreNonFatalException
file
- a file containing the value of the datumTripleStoreNonFatalException
public static Datum createText(long sourceNr, long tripleNr, long summaryValue)
sourceNr
- the numeric identifier of the source of the
triple whose object is the value of the datumtripleNr
- the numeric identifier in its source of the
triple whose object is the value of the datumsummaryValue
- the summary of the triple object's valuepublic static Datum createBinary(byte[] bytes) throws TripleStoreNonFatalException
bytes
- the value of the datumTripleStoreNonFatalException
public static Datum createBinary(java.io.File file) throws TripleStoreNonFatalException
file
- a file containing the value of the datumTripleStoreNonFatalException
public static Datum createBinary(long sourceNr, long tripleNr, long summaryValue)
sourceNr
- the numeric identifier of the source of the
triple whose object is the value of the datumtripleNr
- the numeric identifier in its source of the
triple whose object is the value of the datumsummaryValue
- the summary of the triple object's valuepublic boolean heldInSource()
public Item getItemValue() throws TripleStoreNonFatalException
TripleStoreNonFatalException
public boolean getBooleanValue() throws TripleStoreNonFatalException
TripleStoreNonFatalException
public long getIntegralValue() throws TripleStoreNonFatalException
TripleStoreNonFatalException
public double getRealValue() throws TripleStoreNonFatalException
TripleStoreNonFatalException
public java.lang.String getTextValueAsString() throws TripleStoreNonFatalException, SourceConnectorException
Get the value of the datum as a String if it is a TEXT object, or throw an exception if it is not.
NOTE that the value can be very large. This method should only be used where it is known that the value is not too large.
SourceConnectorException
TripleStoreNonFatalException
public java.lang.String getTextValueForDisplay() throws TripleStoreNonFatalException, SourceConnectorException
SourceConnectorException
TripleStoreNonFatalException
public java.io.BufferedReader getTextValueReader() throws TripleStoreNonFatalException, SourceConnectorException
TripleStoreNonFatalException
SourceConnectorException
public byte[] getBinaryValueAsArray() throws TripleStoreNonFatalException, SourceConnectorException
Get the value of the datum as a byte array if it is a BINARY object
NOTE that the value can be very large. This method should only be used where it is known that the value is not too large.
SourceConnectorException
TripleStoreNonFatalException
public java.lang.String getBinaryValueForDisplay() throws TripleStoreNonFatalException, SourceConnectorException
SourceConnectorException
TripleStoreNonFatalException
public java.io.BufferedInputStream getBinaryValueStream() throws TripleStoreNonFatalException, SourceConnectorException
TripleStoreNonFatalException
SourceConnectorException
public int compareTo(Datum d)
Compare to another datum. Note that the summaries of TEXT and BINARY values are compared first, and the actual values are only compared if the summaries are equal. This means that a result of zero is returned if, and only if, the values are equal but, if the summaries are not equal, then the value returned (-1 or 1) does not correspond to the natural comparison between the values. For example, if the datum is a TEXT datum and its value is lexicographically less than the value of a TEXT datum with which it is compared, but its summary is greater than the summary of the other datum, a result of +1 will be returned, not -1.
This enables comparisons to be made without retrieving large values unless their summaries are equal.
compareTo
in interface java.lang.Comparable<Datum>
public int lexicalCompareTo(Datum d) throws TripleStoreNonFatalException, SourceConnectorException
d
- another datumSourceConnectorException
TripleStoreNonFatalException
public abstract boolean valueShouldBeRead()
public abstract int getLength() throws TripleStoreNonFatalException
TripleStoreNonFatalException
public abstract java.lang.String print()
public abstract java.lang.String simpleTextRepresentation()
public java.lang.String toString()
toString
in class java.lang.Object
public static int lengthComponent(long summary)
Get the length of a text or binary object from its summary value.
The length of a text or binary object is contained in the top 32 bits of the summary value.
summary
- the summary value of a text or
binary objectpublic static long getSummary(Item item)
item
- an itempublic static long getSummary(boolean b)
b
- a boolean valuepublic static long getSummary(long integral)
integral
- an integerpublic static long getSummary(double real)
real
- a real numberpublic static long updateSummary(long summary, java.nio.ByteBuffer buf) throws TripleStoreNonFatalException
summary
- the summary of the sequence of bytes to which
more are to be added.buf
- a buffer containing the bytes to be addedTripleStoreNonFatalException
public static long updateSummary(long summary, byte[] buf) throws TripleStoreNonFatalException
summary
- the summary of the sequence of bytes to which
more are to be added.buf
- a byte array containing the bytes to be added,
which occupy the whole of the array.TripleStoreNonFatalException
public static long updateSummary(long summary, byte[] buf, int length) throws TripleStoreNonFatalException
summary
- the summary of the sequence of bytes to which
more are to be added.buf
- a byte array containing the bytes to be added,
which occupy the first part of the array.length
- the number of bytes to be added. If this is
greater than the length of the array then the whole of the
array is added.TripleStoreNonFatalException
public static long updateSummary(long summary, java.lang.String string) throws TripleStoreNonFatalException
summary
- the summary of the piece of text to which the
text string is to be added.string
- the string to be added.TripleStoreNonFatalException
public static long updateSummary(long summary, char c) throws TripleStoreNonFatalException
summary
- the summary of the piece of text to which the
character is to be added.c
- the character to be added.TripleStoreNonFatalException
public static long updateSummary(long summary, char[] buf) throws TripleStoreNonFatalException
summary
- the summary of the piece of text to which
more characters are to be added.buf
- an array containing the characters to be added,
which occupy the whole of the array.TripleStoreNonFatalException
public static long updateSummary(long summary, char[] buf, int length) throws TripleStoreNonFatalException
summary
- the summary of the piece of text to which
more characters are to be added.buf
- an array containing the characters to be added,
which occupy the first part of the array.length
- the number of characters to be added. If this is
greater than the length of the array then the whole of the
array is added.TripleStoreNonFatalException
public static boolean getBooleanValueFromSummary(long summary)
summary
- a summary of a boolean valuepublic static long getIntegralValueFromSummary(long summary)
summary
- a summary of an integral valuepublic static double getRealValueFromSummary(long summary)
summary
- a summary of a real number valuepublic static byte[] getBytesFromStream(java.io.BufferedInputStream stream) throws TripleStoreNonFatalException
stream
- a BufferedInputStream from which the
bytes are to be readTripleStoreNonFatalException
- if an IO error occurspublic static java.lang.String getByteString(byte[] bytes)
bytes
- a byte arraypublic static byte[] parseByteString(java.lang.String s)
s
- a string that is a text representation of a sequence
of bytespublic org.json.simple.JSONObject toJsonObject() throws SourceConnectorStateException, TripleStoreNonFatalException
SourceConnectorStateException
TripleStoreNonFatalException