com.sparsity.dex.gdb
Class Graph

java.lang.Object
  extended by com.sparsity.dex.gdb.Graph

public class Graph
extends java.lang.Object

Graph class.

Each Database has a Graph associated, which is the persistent graph which contains all data stored into the graph database and is retrieved from a Session.

Check out the 'API' and the 'DEX graph database' sections in the DEX User Manual for more details on the use of this class.

Author:
Sparsity Technologies http://www.sparsity-technologies.com

Method Summary
 void backup(java.lang.String file)
          Dumps all the data to a backup file.
 long countEdges()
          Gets the number of edges.
 long countNodes()
          Gets the number of nodes.
 long degree(long oid, int etype, EdgesDirection dir)
          Gets the number of edges from or to the given node OID and for the given edge type.
 void drop(long oid)
          Drops the given OID.
 void drop(Objects objs)
          Drops all the OIDs from the given collection.
 void dumpData(java.lang.String file)
          Dumps logical data to a file.
 void dumpStorage(java.lang.String file)
          Dumps internal storage data to a file.
 Objects edges(int etype, long tail, long head)
          Gets all the edges of the given type between two given nodes (tail and head).
 Objects explode(long oid, int etype, EdgesDirection dir)
          Selects all edges from or to the given node OID and for the given edge type.
 Objects explode(Objects objs, int etype, EdgesDirection dir)
          Selects all edges from or to each of the node OID in the given collection and for the given edge type.
 void export(java.lang.String file, ExportType type, ExportManager e)
          Exports the Graph.
 int findAttribute(int type, java.lang.String name)
          Gets the Dex attribute identifier for the given type identifier and attribute name.
 AttributeList findAttributes(int type)
          Gets all existing Dex attribute identifiers for the given type identifier.
 long findEdge(int etype, long tail, long head)
          Gets any of the edges of the given type between two given nodes (tail and head).
 TypeList findEdgeTypes()
          Gets all existing Dex edge type identifiers.
 TypeList findNodeTypes()
          Gets all existing Dex node type identifiers.
 long findObject(int attr, Value v)
          Finds one object having the given Value for the given attribute.
 int findType(java.lang.String name)
          Gets the Dex type identifier for the given type name.
 TypeList findTypes()
          Gets all existing Dex node and edge type identifiers.
 Attribute getAttribute(int attr)
          Gets information about the given attribute.
 Value getAttribute(long oid, int attr)
          Gets the Value for the given attribute and OID.
 void getAttribute(long oid, int attr, Value v)
          Gets the Value for the given attribute and OID.
 long getAttributeIntervalCount(int attr, Value lower, boolean includeLower, Value higher, boolean includeHigher)
          Gets how many objects have a value into the given range for the given attribute.
 AttributeList getAttributes(long oid)
          Gets all Dex attribute identifiers with a non-NULL value for the given Dex OID.
 AttributeStatistics getAttributeStatistics(int attr, boolean basic)
          Gets statistics from the given attribute.
 TextStream getAttributeText(long oid, int attr)
          Gets the read-only TextStream for the given text attribute and OID.
 EdgeData getEdgeData(long edge)
          Gets information about an edge.
 long getEdgePeer(long edge, long node)
          Gets the other end for the given edge.
 int getObjectType(long oid)
          Gets the Dex node or edge type identifier for the given OID.
 Type getType(int type)
          Gets information about the given type.
 Values getValues(int attr)
          Gets the Value collection for the given attribute.
 Objects heads(Objects edges)
          Gets all the heads from the given edges collection.
 void indexAttribute(int attr, AttributeKind kind)
          Updates the index of the given attribute.
 Objects neighbors(long oid, int etype, EdgesDirection dir)
          Selects all neighbor nodes from or to the given node OID and for the given edge type.
 Objects neighbors(Objects objs, int etype, EdgesDirection dir)
          Selects all neighbor nodes from or to each of the node OID in the given collection and for the given edge type.
 int newAttribute(int type, java.lang.String name, DataType dt, AttributeKind kind)
          Creates a new attribute.
 int newAttribute(int type, java.lang.String name, DataType dt, AttributeKind kind, Value defaultValue)
          Creates a new attribute with a default value.
 long newEdge(int type, int tailAttr, Value tailV, int headAttr, Value headV)
          Creates a new edge instance.
 long newEdge(int type, long tail, long head)
          Creates a new edge instance.
 int newEdgeType(java.lang.String name, boolean directed, boolean neighbors)
          Creates a new edge type.
 long newNode(int type)
          Creates a new node instance.
 int newNodeType(java.lang.String name)
          Creates a new node type.
 int newRestrictedEdgeType(java.lang.String name, int tail, int head, boolean neighbors)
          Creates a new restricted edge type.
 int newSessionAttribute(int type, DataType dt, AttributeKind kind)
          Creates a new Session attribute.
 int newSessionAttribute(int type, DataType dt, AttributeKind kind, Value defaultValue)
          Creates a new Session attribute with a default value.
 void removeAttribute(int attr)
          Removes the given attribute.
 void removeType(int type)
          Removes the given type.
 Objects select(int type)
          Selects all OIDs belonging to the given type.
 Objects select(int attr, Condition cond, Value v)
          Selects all OIDs satisfying the given condition for the given attribute.
 Objects select(int attr, Condition cond, Value lower, Value higher)
          Selects all OIDs satisfying the given condition for the given attribute.
 void setAttribute(long oid, int attr, Value v)
          Sets the Value for the given attribute and OID.
 void setAttributeDefaultValue(int attr, Value v)
          Sets a default value for an attribute.
 void setAttributeText(long oid, int attr, TextStream tstream)
          Sets the writable TextStream for the given text attribute and OID.
 Objects tails(Objects edges)
          Gets all the tails from the given edges collection.
 void tailsAndHeads(Objects edges, Objects tails, Objects heads)
          Gets all the tails and heads from the given edges collection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

setAttributeText

public void setAttributeText(long oid,
                             int attr,
                             TextStream tstream)
Sets the writable TextStream for the given text attribute and OID.

Parameters:
oid - [in] Dex OID.
attr - [in] Dex attribute identifier.
tstream - [in] New Text value. This corresponds to a TextStream to write.

dumpData

public void dumpData(java.lang.String file)
              throws java.io.FileNotFoundException,
                     java.lang.RuntimeException
Dumps logical data to a file.

Parameters:
file - [in] Output file path.
Throws:
java.io.FileNotFoundException - If the given file cannot be created.
java.lang.RuntimeException - null

findTypes

public TypeList findTypes()
Gets all existing Dex node and edge type identifiers.

Returns:
Dex node and edge type identifier list.

setAttribute

public void setAttribute(long oid,
                         int attr,
                         Value v)
Sets the Value for the given attribute and OID.

Parameters:
oid - [in] Dex OID.
attr - [in] Dex attribute identifier.
v - [in] Value for the given attribute and for the given OID.

select

public Objects select(int attr,
                      Condition cond,
                      Value v)
Selects all OIDs satisfying the given condition for the given attribute.

Parameters:
attr - [in] Dex attribute identifier.
cond - [in] Condition to be satisfied.
v - [in] Value to be satisfied.
Returns:
Objects instance.

getAttributeIntervalCount

public long getAttributeIntervalCount(int attr,
                                      Value lower,
                                      boolean includeLower,
                                      Value higher,
                                      boolean includeHigher)
Gets how many objects have a value into the given range for the given attribute.

This only works for AttributeKind::Indexed or AttributeKind::Unique attributes.

Given values must belong to the same DataType than the attribute.

Parameters:
attr - [in] Dex attribute identifier.
lower - [in] Lower bound Value of the range.
includeLower - [in] If TRUE, include lower bound Value of the range.
higher - [in] Higher bound Value of the range.
includeHigher - [in] If TRUE, include higher bound Value of the range.
Returns:
Number of objects having a value into the given range.

tailsAndHeads

public void tailsAndHeads(Objects edges,
                          Objects tails,
                          Objects heads)
Gets all the tails and heads from the given edges collection.

Parameters:
edges - [in] Dex edge identifier collection.
tails - [in|out] If not NULL, all the tails will be stored here.
heads - [in|out] If not NULL, all the heads will be stored here.

degree

public long degree(long oid,
                   int etype,
                   EdgesDirection dir)
Gets the number of edges from or to the given node OID and for the given edge type.

Parameters:
oid - [in] Dex node OID.
etype - [in] Dex edge type identifier.
dir - [in] Direction.
Returns:
The number of edges.

dumpStorage

public void dumpStorage(java.lang.String file)
                 throws java.io.FileNotFoundException,
                        java.lang.RuntimeException
Dumps internal storage data to a file.

Parameters:
file - [in] Output file path.
Throws:
java.io.FileNotFoundException - If the given file cannot be created.
java.lang.RuntimeException - null

neighbors

public Objects neighbors(Objects objs,
                         int etype,
                         EdgesDirection dir)
Selects all neighbor nodes from or to each of the node OID in the given collection and for the given edge type.

Parameters:
objs - [in] Dex node OID collection.
etype - [in] Dex edge type identifier.
dir - [in] Direction.
Returns:
Objects instance.

export

public void export(java.lang.String file,
                   ExportType type,
                   ExportManager e)
Exports the Graph.

Parameters:
file - [in] Output file.
type - [in] Export type.
e - [in] Defines how to do the export for each graph object.

getAttributes

public AttributeList getAttributes(long oid)
Gets all Dex attribute identifiers with a non-NULL value for the given Dex OID.

Parameters:
oid - [in] Dex OID.
Returns:
Dex attribute identifier list.

getAttributeStatistics

public AttributeStatistics getAttributeStatistics(int attr,
                                                  boolean basic)
Gets statistics from the given attribute.

Parameters:
attr - [in] Dex attribute identifier.
basic - [in] If FALSE all statistics are computed, if TRUE just those statistics marked as basic will be computed (see description of the AttributeStatistics class). Of course, computing just basic statistics will be faster than computing all of them.
Returns:
An AttributeStatistics instace.

newNode

public long newNode(int type)
Creates a new node instance.

Parameters:
type - [in] Dex type identifier.
Returns:
Unique OID of the new node instance.

getAttributeText

public TextStream getAttributeText(long oid,
                                   int attr)
Gets the read-only TextStream for the given text attribute and OID.

Parameters:
oid - [in] Dex OID.
attr - [in] Dex attribute identifier.
Returns:
A TextStream. This returns a TextStream to read.

countEdges

public long countEdges()
Gets the number of edges.

Returns:
The number of edges.

select

public Objects select(int attr,
                      Condition cond,
                      Value lower,
                      Value higher)
Selects all OIDs satisfying the given condition for the given attribute.

This allows to perform the Condition::Between operation, thus it has two Value arguments.

Parameters:
attr - [in] Dex attribute identifier.
cond - [in] Condition to be satisfied. It must be Condition::Between.
lower - [in] Lower-bound Value to be satisfied.
higher - [in] Higher-bound Value to be satisfied.
Returns:
Objects instance.

findEdgeTypes

public TypeList findEdgeTypes()
Gets all existing Dex edge type identifiers.

Returns:
Dex edge type identifier list.

indexAttribute

public void indexAttribute(int attr,
                           AttributeKind kind)
Updates the index of the given attribute.

This just works if the current index of the attribute corresponds to AttributeKind::Basic and the new one is AttributeKind::Indexed or AttributeKind::Unique.

Parameters:
attr - [in] Dex attribute identifier.
kind - [in] Attribute kind.

getType

public Type getType(int type)
Gets information about the given type.

Parameters:
type - [in] Dex type identifier.
Returns:
The Type for the given Dex type identifier.

setAttributeDefaultValue

public void setAttributeDefaultValue(int attr,
                                     Value v)
Sets a default value for an attribute.

The default value will be applied to all the new nodes or edges.

The given value must have the same DataType as the attribute or be a NULL value to remove the current default value.

Parameters:
attr - [in] The attribute.
v - [in] The default value to use for this attribute.

findAttribute

public int findAttribute(int type,
                         java.lang.String name)
Gets the Dex attribute identifier for the given type identifier and attribute name.

Parameters:
type - [in] Dex type identifier.
name - [in] Unique attribute name.
Returns:
The Dex attribute identifier for the given type and attribute name or Attribute::InvalidAttribute if there is no attribute with the given name for the given type.

newAttribute

public int newAttribute(int type,
                        java.lang.String name,
                        DataType dt,
                        AttributeKind kind)
Creates a new attribute.

Parameters:
type - [in] Dex node or edge type identifier.
name - [in] Unique name for the new attribute.
dt - [in] Data type for the new attribute.
kind - [in] Attribute kind.
Returns:
Unique Dex attribute identifier.

edges

public Objects edges(int etype,
                     long tail,
                     long head)
Gets all the edges of the given type between two given nodes (tail and head).

type[in] Dex edge type identifier.

Parameters:
etype - null
tail - [in] Tail node identifier.
head - [in] Head node identifier.
Returns:
Objects instance.

select

public Objects select(int type)
Selects all OIDs belonging to the given type.

Parameters:
type - [in] Dex type identifier.
Returns:
Objects instance.

findNodeTypes

public TypeList findNodeTypes()
Gets all existing Dex node type identifiers.

Returns:
Dex node type identifier list.

getAttribute

public Value getAttribute(long oid,
                          int attr)
Gets the Value for the given attribute and OID.

The other version of this call, where the Value is an output parameter instead of the return, is better because it allows the user to reuse an existing Value instance, whereas this call always creates a new Value instance to be returned.

It never returns NULL. Thus, in case the OID has a NULL value for the attribute it returns a NULL Value instance.

Parameters:
oid - [in] Dex OID.
attr - [in] Dex attribute identifier.
Returns:
A new Value instance having the attribute value for the given OID.

removeAttribute

public void removeAttribute(int attr)
Removes the given attribute.

Parameters:
attr - [in] Dex attribute identifier.

backup

public void backup(java.lang.String file)
            throws java.io.FileNotFoundException,
                   java.lang.RuntimeException
Dumps all the data to a backup file.

See Dex::Restore.

Parameters:
file - [in] Output backup file path.
Throws:
java.io.FileNotFoundException - If the given file cannot be created.
java.lang.RuntimeException - null

newSessionAttribute

public int newSessionAttribute(int type,
                               DataType dt,
                               AttributeKind kind,
                               Value defaultValue)
Creates a new Session attribute with a default value.

Session attributes are exclusive for the Session (just its Session can use the attribute) and are automatically removed when the Session is closed (thus, attribute data is not persistent into the database).

Since they are not persistent, they cannot be retrieved from the database, so they do not have an identifier name.

Parameters:
type - [in] Dex node or edge type identifier.
dt - [in] Data type for the new attribute.
kind - [in] Attribute kind.
defaultValue - [in] The default value to use in each new node/edge.
Returns:
Unique Dex attribute identifier.

findAttributes

public AttributeList findAttributes(int type)
Gets all existing Dex attribute identifiers for the given type identifier.

Parameters:
type - [in] Dex type identifier.
Returns:
Dex attribute identifier list.

countNodes

public long countNodes()
Gets the number of nodes.

Returns:
The number of nodes.

getEdgeData

public EdgeData getEdgeData(long edge)
Gets information about an edge.

Parameters:
edge - [in] Dex edge identifier.
Returns:
An EdgeData instance.

neighbors

public Objects neighbors(long oid,
                         int etype,
                         EdgesDirection dir)
Selects all neighbor nodes from or to the given node OID and for the given edge type.

Parameters:
oid - [in] Dex node OID.
etype - [in] Dex edge type identifier.
dir - [in] Direction.
Returns:
Objects instance.

explode

public Objects explode(Objects objs,
                       int etype,
                       EdgesDirection dir)
Selects all edges from or to each of the node OID in the given collection and for the given edge type.

Parameters:
objs - [in] Dex node OID collection.
etype - [in] Dex edge type identifier.
dir - [in] Direction.
Returns:
Objects instance.

newNodeType

public int newNodeType(java.lang.String name)
Creates a new node type.

Parameters:
name - [in] Unique name for the new node type.
Returns:
Unique Dex type identifier.

newSessionAttribute

public int newSessionAttribute(int type,
                               DataType dt,
                               AttributeKind kind)
Creates a new Session attribute.

Session attributes are exclusive for the Session (just its Session can use the attribute) and are automatically removed when the Session is closed (thus, attribute data is not persistent into the database).

Since they are not persistent, they cannot be retrieved from the database, so they do not have an identifier name.

Parameters:
type - [in] Dex node or edge type identifier.
dt - [in] Data type for the new attribute.
kind - [in] Attribute kind.
Returns:
Unique Dex attribute identifier.

tails

public Objects tails(Objects edges)
Gets all the tails from the given edges collection.

Parameters:
edges - [in] Dex edge identifier collection.
Returns:
The tails collection.

drop

public void drop(long oid)
Drops the given OID.

It also removes its egdges as well as its attribute values.

Parameters:
oid - [in] Dex OID to be removed.

newEdgeType

public int newEdgeType(java.lang.String name,
                       boolean directed,
                       boolean neighbors)
Creates a new edge type.

Parameters:
name - [in] Unique name for the new edge type.
directed - [in] If TRUE, this creates a directed edge type, otherwise this creates a undirected edge type.
neighbors - [in] If TRUE, this indexes neighbor nodes, otherwise not.
Returns:
Unique Dex type identifier.

heads

public Objects heads(Objects edges)
Gets all the heads from the given edges collection.

Parameters:
edges - [in] Dex edge identifier collection.
Returns:
The heads collection.

findEdge

public long findEdge(int etype,
                     long tail,
                     long head)
Gets any of the edges of the given type between two given nodes (tail and head).

If there are more than one, then any of them will be returned. And in case there are no edge between the given tail and head, Objects::InvalidOID will be returned.

Parameters:
etype - [in] Dex edge type identifier.
tail - [in] Tail node identifier.
head - [in] Head node identifier.
Returns:
Any of the edges or Objects::InvalidOID.

explode

public Objects explode(long oid,
                       int etype,
                       EdgesDirection dir)
Selects all edges from or to the given node OID and for the given edge type.

Parameters:
oid - [in] Dex node OID.
etype - [in] Dex edge type identifier.
dir - [in] Direction.
Returns:
Objects instance.

drop

public void drop(Objects objs)
Drops all the OIDs from the given collection.

See Drop method with the single OID parameter. This performs that call for all the elements into the collection.

Parameters:
objs - [in] Objects collection with the OIDs to be removed.

newAttribute

public int newAttribute(int type,
                        java.lang.String name,
                        DataType dt,
                        AttributeKind kind,
                        Value defaultValue)
Creates a new attribute with a default value.

Parameters:
type - [in] Dex node or edge type identifier.
name - [in] Unique name for the new attribute.
dt - [in] Data type for the new attribute.
kind - [in] Attribute kind.
defaultValue - [in] The default value to use in each new node/edge.
Returns:
Unique Dex attribute identifier.

getObjectType

public int getObjectType(long oid)
Gets the Dex node or edge type identifier for the given OID.

Parameters:
oid - [in] Dex OID.
Returns:
Dex node or edge type identifier.

getAttribute

public Attribute getAttribute(int attr)
Gets information about the given attribute.

Parameters:
attr - [in] Dex attribute identifier.
Returns:
The Attribute for the given Dex attribute identifier.

newEdge

public long newEdge(int type,
                    int tailAttr,
                    Value tailV,
                    int headAttr,
                    Value headV)
Creates a new edge instance.

The tail of the edge will be any node having the given tailV Value for the given tailAttr attribute identifier, and the head of the edge will be any node having the given headV Value for the given headAttr attribute identifier.

Parameters:
type - [in] Dex type identifier.
tailAttr - [in] Dex attribute identifier.
tailV - [in] Value.
headAttr - [in] Dex attribute identifier.
headV - [in] Value.
Returns:
Unique OID of the new edge instance.

getValues

public Values getValues(int attr)
Gets the Value collection for the given attribute.

Parameters:
attr - [in] Dex attribute identifier.

getEdgePeer

public long getEdgePeer(long edge,
                        long node)
Gets the other end for the given edge.

Parameters:
edge - [in] Dex edge identifier.
node - [in] Dex node identifier. It must be one of the ends of the edge.
Returns:
The other end of the edge.

findObject

public long findObject(int attr,
                       Value v)
Finds one object having the given Value for the given attribute.

If there are more than one, then any of them will be returned. And in case there are no object having this Value, Objects::InvalidOID will be returned.

Parameters:
attr - [in] Dex attribute identifier.
v - [in] Value.
Returns:
Dex OID or Objects::InvalidOID.

newEdge

public long newEdge(int type,
                    long tail,
                    long head)
Creates a new edge instance.

Parameters:
type - [in] Dex type identifier.
tail - [in] Source Dex OID.
head - [in] Target Dex OID.
Returns:
Unique OID of the new edge instance.

findType

public int findType(java.lang.String name)
Gets the Dex type identifier for the given type name.

Parameters:
name - [in] Unique type name.
Returns:
The Dex type identifier for the given type name or Type::InvalidType if there is no type with the given name.

getAttribute

public void getAttribute(long oid,
                         int attr,
                         Value v)
Gets the Value for the given attribute and OID.

Parameters:
oid - [in] Dex OID.
attr - [in] Dex attribute identifier.
v - [in|out] Value for the given attribute and for the given OID.

removeType

public void removeType(int type)
Removes the given type.

This fails if there exist attributes defined for the type or if there exist restricted edges referencing this type.

Parameters:
type - [in] Dex type identifier.

newRestrictedEdgeType

public int newRestrictedEdgeType(java.lang.String name,
                                 int tail,
                                 int head,
                                 boolean neighbors)
Creates a new restricted edge type.

Parameters:
name - [in] Unique name for the new edge type.
tail - [in] Tail Dex node type identifier.
head - [in] Head Dex node type identifier.
neighbors - [in] If TRUE, this indexes neighbor nodes, otherwise not.
Returns:
Unique Dex type identifier.