edu.upc.dama.dex.core
Class Objects

java.lang.Object
  edu.upc.dama.dex.core.Objects

All Implemented Interfaces:

java.io.Closeable, java.lang.Iterable, java.util.Collection, java.util.Set

public class Objects
extends java.lang.Object
implements java.io.Closeable, java.util.Set

Object identifier collection.

It stores a collection of DEX object identifiers as a set of long values where there is no duplicated values. The memory management is done by the parent GraphPool.

This class should be used just to store large collections. Otherwise, it is strongly recommended to use common classes from the Java API.

This class is NOT thread safe.

Known problems:

Object identifiers cannot be removed from Objects while Iterators are still opened. That is, a code as follows may have unexpected and fatal results:

 Objects objs = ...
 Objects.Iterator it = objs.iterator();
 while (it.hasNext()) {
   long oid = it.next();
   if (...) {
     objs.remove(oid);
   }
 }
 it.close();
 objs.close();
 

Also, in case Objects has been obtained directly from a Graph, this collection cannot be updated through its original Graph. That is, a code as follows may have unexpected and fatal results:

 Objects objs = graph.select(attr, Graph.OPERATION_EQ, value); // or something similar
 Objects.Iterator it objs.iterator();
 while (it.hasNext()) {
   long oid = it.next();
   if (...) {
     graph.setAttribute(oid, attr, newvalue);
   }
 }
 it.close();
 objs.close();
 

Author:

Sparsity Technologies

Nested Class Summary

static class	Objects.Combine Deprecated. As of release 1.2, replace by Objects.COMBINE_UNION, Objects.COMBINE_DIFFERENCE and Objects.COMBINE_INTERSECTION.
class	Objects.Iterator Iterator to traverse the object identifier in a collection.

Field Summary

static short	COMBINE_DIFFERENCE Difference combine operation.
static short	COMBINE_INTERSECTION Intersection combine operation.
static short	COMBINE_UNION Union combine operation.

Constructor Summary

Objects(Session sess)
Creates a new instance of Objects.

Objects(Session sess, Objects objs)
Creates a new instance of Objects which is a copy of the given one.

Objects(Session sess, Objects objs1, Objects objs2, Objects.Combine c)
Deprecated. As of release 1.2, replace by Objects.Objects(Session,Objects,Objects,short).

Objects(Session sess, Objects objs1, Objects objs2, short combine)
Creates a new instance of Objects which is the combination of the two given collections.

Method Summary

boolean	add(long oid) Adds an object identifier to the collection.
boolean	add(java.lang.Long e) Adds the specified element to this set if it is not already present (optional operation).
boolean	addAll(java.util.Collection clctn) Adds all of the elements in the specified collection to this set if they're not already present (optional operation).
void	clear() Removes all the object identifiers.
void	close() Closes the collection and all their non-closed iterators.
boolean	contains(java.lang.Object o) Returns true if this collections contains the specified element.
boolean	containsAll(java.util.Collection clctn) Returns true if this set contains all of the elements of the specified collection.
long	difference(Objects objs) Performs the difference operation with the given collection.
static Objects	difference(Session sess, Objects objs1, Objects objs2) Creates a new instance of Objects which is the difference of the two given collections.
boolean	exists(long oid) Gets whether the object identifier exists in the collection or not.
long	first() Gets the first object identifier in the collection.
Session	getSession() Gets the parent Session instance.
long	intersection(Objects objs) Performs the intersection operation with the given collection.
static Objects	intersection(Session sess, Objects objs1, Objects objs2) Creates a new instance of Objects which is the intersection of the two given collections.
boolean	isEmpty() Returns true if this Objects contains no elements.
boolean	isOpen() Gets if the Objects instance is open.
Objects.Iterator	iterator() Gets an Objects.Iterator.
Objects.Iterator	iterator(long startPosition) Gets an Objects.Iterator.
Objects.Iterator	iteratorFromOID(long oid) Gets an Objects.Iterator pointing tot the given object.
long	next(long oid, boolean exists) Gets the next object identifier in the collection from the given one.
boolean	remove(long oid) Removes the given object identifier.
boolean	remove(java.lang.Object o) Removes the specified element from this set if it is present (optional operation).
boolean	removeAll(java.util.Collection clctn) Removes from this set all of its elements that are contained in the specified collection (optional operation).
boolean	retainAll(java.util.Collection clctn) Retains only the elements in this set that are contained in the specified collection (optional operation).
static Objects	sample(Session sess, Objects src, Objects exclude, long samples) Creates a new instance of Objects which is a sample of a given collection excluding the objects of another one.
int	size() Get the number of object identifiers in this collection (its cardinality).
long	sizeLong() As Objects.size() but it returns a long which can be larger than Integer.MAX_VALUE.
java.lang.Object[]	toArray() Returns an array containing all of the object identifiers in this set.
java.lang.Object[]	toArray(java.lang.Object[] ts) Returns an array containing all of the object identifiers in this set; the runtime type of the returned array is that of the specified array.
long	union(Objects objs) Performs the union operation with the given collection.
static Objects	union(Session sess, Objects objs1, Objects objs2) Creates a new instance of Objects which is the union of the two given collections.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Set

equals, hashCode

Field Detail

COMBINE_UNION

public static final short COMBINE_UNION

Union combine operation.

See Also:

Constant Field Values

COMBINE_INTERSECTION

public static final short COMBINE_INTERSECTION

Intersection combine operation.

See Also:

Constant Field Values

COMBINE_DIFFERENCE

public static final short COMBINE_DIFFERENCE

Difference combine operation.

See Also:

Constant Field Values

Constructor Detail

Objects

public Objects(Session sess)

Creates a new instance of Objects.

It creates a new empty collection.

Parameters:

sess - Parent Session.

Objects

public Objects(Session sess,
               Objects objs)

Creates a new instance of Objects which is a copy of the given one.

Parameters:

sess - Parent Session instance.

objs - Objects instance.

Objects

public Objects(Session sess,
               Objects objs1,
               Objects objs2,
               short combine)

Creates a new instance of Objects which is the combination of the two given collections.

Parameters:

sess - Parent Session.

objs1 - Objects instance.

objs2 - Objects instance.

combine - Combine operation. It must be Objects.COMBINE_UNION, Objects.COMBINE_INTERSECTION, or Objects.COMBINE_DIFFERENCE.

Objects

@Deprecated
public Objects(Session sess,
                          Objects objs1,
                          Objects objs2,
                          Objects.Combine c)

Deprecated. As of release 1.2, replace by Objects.Objects(Session,Objects,Objects,short).

Creates a new instance of Objects which is the combination of the two given collections.

Parameters:

sess - Parent Session.

objs1 - Objects instance.

objs2 - Objects instance.

c - Combine operation.

Method Detail

union

public static Objects union(Session sess,
                            Objects objs1,
                            Objects objs2)

Creates a new instance of Objects which is the union of the two given collections.

Parameters:

sess - Parent Session.

objs1 - Objects instance.

objs2 - Objects instance.

Returns:

A new Objects which is the union of the two given collections.

intersection

public static Objects intersection(Session sess,
                                   Objects objs1,
                                   Objects objs2)

Creates a new instance of Objects which is the intersection of the two given collections.

Parameters:

sess - Parent Session.

objs1 - Objects instance.

objs2 - Objects instance.

Returns:

A new Objects which is the intersection of the two given collections.

difference

public static Objects difference(Session sess,
                                 Objects objs1,
                                 Objects objs2)

Creates a new instance of Objects which is the difference of the two given collections.

Parameters:

sess - Parent Session.

objs1 - Objects instance.

objs2 - Objects instance.

Returns:

A new Objects which is the difference of the two given collections.

getSession

public Session getSession()

Gets the parent Session instance.

Returns:

The parent Session instance.

isOpen

public boolean isOpen()

Gets if the Objects instance is open.

Only opened Objects instances can execute methods, otherwise they will fail.

Returns:

true if the Objects instance is open, false otherwise.

close

public void close()

Closes the collection and all their non-closed iterators.

It is important to close Objects as soon as possible to free its memory resources.

Specified by:

close in interface java.io.Closeable

See Also:

Objects.Iterator

sizeLong

public long sizeLong()

As Objects.size() but it returns a long which can be larger than Integer.MAX_VALUE.

Returns:

Number of elements into the collection.

add

public boolean add(long oid)

Adds an object identifier to the collection.

Parameters:

oid - Object identifier.

Returns:

true if the object identifier is successfully added to the collection or false if the object identifier was alredy in the collection.

exists

public boolean exists(long oid)

Gets whether the object identifier exists in the collection or not.

Parameters:

oid - Object identifier.

Returns:

true if the object identifier exists in the collection or false otherwise.

first

public long first()

Gets the first object identifier in the collection.

The first object identifier is that with the smaller value. The collection must have at least one element.

Returns:

The first object identifier in the collection.

next

public long next(long oid,
                 boolean exists)

Gets the next object identifier in the collection from the given one.

Parameters:

oid - Object identifier.

exists - If true, oid must exists into the collection.

Returns:

The next object identifier in the collection from the given one.

remove

public boolean remove(long oid)

Removes the given object identifier.

Parameters:

oid - Object identifier.

Returns:

true if the object identifier is successfully removed, false if the object identifier was not in the collection.

clear

public void clear()

Removes all the object identifiers.

Specified by:

clear in interface java.util.Collection

Specified by:

clear in interface java.util.Set

union

public long union(Objects objs)

Performs the union operation with the given collection.

All the object identifiers in the objs collection are added to the calling instance collection.

Parameters:

objs - Object identifier collection.

Returns:

The resulting size of the calling instance collection.

intersection

public long intersection(Objects objs)

Performs the intersection operation with the given collection.

Only those object identifiers which are present in the objs collection and in the calling instance collection will remain in the calling instance collection, the others will be removed from the calling instance collection.

Parameters:

objs - Object identifier collection.

Returns:

The resulting size of the calling instance collection.

difference

public long difference(Objects objs)

Performs the difference operation with the given collection.

All object identifiers from the calling instance collection will remain in the calling instance collection but those which are present in the objs collection.

Parameters:

objs - Object identifier collection.

Returns:

The resulting size of the calling instance collection.

sample

public static Objects sample(Session sess,
                             Objects src,
                             Objects exclude,
                             long samples)

Creates a new instance of Objects which is a sample of a given collection excluding the objects of another one.

It creates a collection.

Parameters:

sess - Parent Session.

src - Source Objects to be sampled.

exclude - Objects to be excluded.

samples - The number of object samples to be taken.

Returns:

New Objects collection.

iterator

public Objects.Iterator iterator()

Gets an Objects.Iterator.

Specified by:

iterator in interface java.lang.Iterable

Specified by:

iterator in interface java.util.Collection

Specified by:

iterator in interface java.util.Set

Returns:

An Objects.Iterator.

iterator

public Objects.Iterator iterator(long startPosition)

Gets an Objects.Iterator.

Parameters:

startPosition - The number of objects to skip from the beginning [0..Size).

Returns:

An Objects.Iterator.

iteratorFromOID

public Objects.Iterator iteratorFromOID(long oid)

Gets an Objects.Iterator pointing tot the given object.

Parameters:

oid - The identifier of the object.

Returns:

An Objects.Iterator.

size

public int size()

Get the number of object identifiers in this collection (its cardinality).

Specified by:

size in interface java.util.Collection

Specified by:

size in interface java.util.Set

Returns:

Number of elements into the collection.

See Also:

Objects.sizeLong()

isEmpty

public boolean isEmpty()

Returns true if this Objects contains no elements.

Specified by:

isEmpty in interface java.util.Collection

Specified by:

isEmpty in interface java.util.Set

Returns:

true if the collection contains no elements.

contains

public boolean contains(java.lang.Object o)

Returns true if this collections contains the specified element.

Specified by:

contains in interface java.util.Collection

Specified by:

contains in interface java.util.Set

Parameters:

o - element whose presence in this set is to be tested.

Returns:

true if this set contains the specified element.

toArray

public java.lang.Object[] toArray()

Returns an array containing all of the object identifiers in this set. Obeys the general contract of the Collection.toArray method.

Specified by:

toArray in interface java.util.Collection

Specified by:

toArray in interface java.util.Set

Returns:

an array containing all of the elements in this set.

toArray

public java.lang.Object[] toArray(java.lang.Object[] ts)

Returns an array containing all of the object identifiers in this set; the runtime type of the returned array is that of the specified array. Obeys the general contract of the Collection.toArray(Object[]) method.

Specified by:

toArray in interface java.util.Collection

Specified by:

toArray in interface java.util.Set

Parameters:

ts - the array into which the elements of this set are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the elements of this set.

add

public boolean add(java.lang.Long e)

Adds the specified element to this set if it is not already present (optional operation). More formally, adds the specified element, o, to this set if this set contains no element e such that (o==null ? e==null : o.equals(e)). If this set already contains the specified element, the call leaves this set unchanged and returns false. In combination with the restriction on constructors, this ensures that sets never contain duplicate elements. The stipulation above does not imply that sets must accept all elements; sets may refuse to add any particular element, including null, and throwing an exception, as described in the specification for Collection.add. Individual set implementations should clearly document any restrictions on the the elements that they may contain.

Specified by:

add in interface java.util.Collection

Specified by:

add in interface java.util.Set

Parameters:

e - element to be added to this set.

Returns:

true if this set did not already contain the specified element.

remove

public boolean remove(java.lang.Object o)

Removes the specified element from this set if it is present (optional operation). More formally, removes an element e such that (o==null ? e==null : o.equals(e)), if the set contains such an element. Returns true if the set contained the specified element (or equivalently, if the set changed as a result of the call). (The set will not contain the specified element once the call returns.)

Specified by:

remove in interface java.util.Collection

Specified by:

remove in interface java.util.Set

Parameters:

o - object to be removed from this set, if present.

Returns:

true if the set contained the specified element.

containsAll

public boolean containsAll(java.util.Collection clctn)

Returns true if this set contains all of the elements of the specified collection. If the specified collection is also a set, this method returns true if it is a subset of this set.

Specified by:

containsAll in interface java.util.Collection

Specified by:

containsAll in interface java.util.Set

Parameters:

clctn - collection to be checked for containment in this set.

Returns:

true if this set contains all of the elements of the specified collection.

addAll

public boolean addAll(java.util.Collection clctn)

Adds all of the elements in the specified collection to this set if they're not already present (optional operation). If the specified collection is also a set, the addAll operation effectively modifies this set so that its value is the union of the two sets. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress.

Specified by:

addAll in interface java.util.Collection

Specified by:

addAll in interface java.util.Set

Parameters:

clctn - collection whose elements are to be added to this set.

Returns:

true if this set changed as a result of the call.

retainAll

public boolean retainAll(java.util.Collection clctn)

Retains only the elements in this set that are contained in the specified collection (optional operation). In other words, removes from this set all of its elements that are not contained in the specified collection. If the specified collection is also a set, this operation effectively modifies this set so that its value is the intersection of the two sets.

Specified by:

retainAll in interface java.util.Collection

Specified by:

retainAll in interface java.util.Set

Parameters:

clctn - collection that defines which elements this set will retain.

Returns:

true if this collection changed as a result of the call.

removeAll

public boolean removeAll(java.util.Collection clctn)

Removes from this set all of its elements that are contained in the specified collection (optional operation). If the specified collection is also a set, this operation effectively modifies this set so that its value is the asymmetric set difference of the two sets.

Specified by:

removeAll in interface java.util.Collection

Specified by:

removeAll in interface java.util.Set

Parameters:

clctn - collection that defines which elements will be removed from this set.

Returns:

true if this set changed as a result of the call.