com.qizx.api
Interface LibraryMember

All Known Subinterfaces:

Collection, Document

public interface LibraryMember

Common interface for objects belonging to a Library, namely Collections and Documents.

Field Summary

static String	COLLECTION Value of the predefined property 'nature' for a Collection, equal to "collection".
static String	DOCUMENT Value of the predefined property 'nature' for a Document, equal to "document".
static String	NATURE Name of the predefined property 'nature', whose value is one of the strings "collection" or "document".
static String	PATH Name of the predefined property 'path', whose value is also returned by the getPath() method.

Method Summary

boolean	contains(LibraryMember other) Returns true if that member (Document or Collection) is contained inside this member.
void	copyTo(String newPath) Copies the Document or Collection to another location.
void	delete() Deletes the Document or Collection.
boolean	exists() Returns true if the member actually exists (not deleted).
long	getIntegerProperty(String propName) Convenience method: returns the integer value of a property.
Library	getLibrary() Returns the Library session owning this member.
String	getName() Returns the name of the member inside its enclosing Collection.
Collection	getParent() Returns the Collection that directly contains this member.
String	getParentPath() Returns the path of the parent of the enclosing Collection.
String	getPath() Returns the complete path of the member inside its Library.
Object	getProperty(String propName) Gets the value of a property by its name.
String[]	getPropertyNames() Returns a sorted list of current property names of the object.
boolean	hasProperty(String propName) Tests if this member has a property of the specified name.
boolean	isCollection() Returns true if the member is a Collection.
boolean	isDocument() Returns true if the member is a Document.
boolean	lock(int timeoutMillis) Starts an update transaction by locking this member (Document or Collection).
Object	removeProperty(String propName) Deletes a property.
void	renameTo(String newPath) Renames the Document or Collection.
Object	setIntegerProperty(String propName, long propValue) Convenience method: defines a long integer property.
Object	setProperty(String propName, Object propValue) Changes the value of a property.

Field Detail

PATH

public static final String PATH

Name of the predefined property 'path', whose value is also returned by the getPath() method.

See Also:

Constant Field Values

NATURE

public static final String NATURE

Name of the predefined property 'nature', whose value is one of the strings "collection" or "document".

See Also:

Constant Field Values

COLLECTION

public static final String COLLECTION

Value of the predefined property 'nature' for a Collection, equal to "collection".

See Also:

Constant Field Values

DOCUMENT

public static final String DOCUMENT

Value of the predefined property 'nature' for a Document, equal to "document".

See Also:

Constant Field Values

Method Detail

exists

public boolean exists()

Returns true if the member actually exists (not deleted).

Returns:

true if the member actually exists

isCollection

public boolean isCollection()

Returns true if the member is a Collection.

Returns:

true if the member is a Collection.

isDocument

public boolean isDocument()

Returns true if the member is a Document.

Returns:

true if the member is a Document.

getPath

public String getPath()

Returns the complete path of the member inside its Library. This path uses forward slashes as separator and always starts with a slash. The root collection has the path "/".

Returns:

a String representing the complete path of the member

getName

public String getName()

Returns the name of the member inside its enclosing Collection. This name cannot contain a slash, except for the root collection, whose name is "/".

Returns:

a String representing the name

getParentPath

public String getParentPath()

Returns the path of the parent of the enclosing Collection. The root collection '/' returns null.

Returns:

a String representing the path of the parent collection

getParent

public Collection getParent()
                     throws DataModelException

Returns the Collection that directly contains this member.

Returns:

the collection which is the parent of this member; null is returned for the root collection ("/").

Throws:

DataModelException - if the library is closed; if the member is already deleted

getLibrary

public Library getLibrary()

Returns the Library session owning this member.

Returns:

a Library session

contains

public boolean contains(LibraryMember other)

Returns true if that member (Document or Collection) is contained inside this member. A library member does not contain itself.

Parameters:

other - another library member to check for containment

Returns:

true if the another library member is contained

lock

public boolean lock(int timeoutMillis)
             throws DataModelException

Starts an update transaction by locking this member (Document or Collection).

This method is almost equivalent to calling Library.lockCollection(java.lang.String, int) or Library.lockDocument(java.lang.String, int) on this Library member.

The difference is that an exception is thrown if it is found that this object no longer exists in the refreshed state of the Library (due to a deletion by another transaction). In contrast, lockCollection and lockDocument simply return null.

Note: this method exists for historical reasons. It is recommended to use lockCollection and lockDocument instead.

Parameters:

timeoutMillis - a maximum time in milliseconds to wait for when the object is already locked. After that time the method returns false and no lock is set.

Returns:

true if the lock is successful.

Throws:

DataModelException - if the member has been deleted by another transaction; if the library is closed

copyTo

public void copyTo(String newPath)
            throws DataModelException

Copies the Document or Collection to another location.

A Collection is recursively copied with all its contents.

As for other updating operations, should be followed by a commit to take effect permanently.

Parameters:

newPath - path of the copy. It is an error (exception thrown) if this path points to an existing Library member.

Throws:

DataModelException - if the library is closed; if the member is already deleted; if the newPath points to an existing member or points inside a non-existing collection,

renameTo

public void renameTo(String newPath)
              throws DataModelException

Renames the Document or Collection.

Upon successful completion, the path of the library member is updated according the path specified.

As for other updating operations, should be followed by a commit to take effect permanently.

Parameters:

newPath - new path of the member. It is an error (exception thrown) if this path points to an existing Member.

Throws:

DataModelException - if the library is closed; if the member is already deleted; if the newPath points to an existing document or points inside a non-existing collection,

delete

public void delete()
            throws DataModelException

Deletes the Document or Collection. As for other updating operations, should be followed by a commit to take effect permanently.

When applied on a Collection, deletes recursively all enclosed documents and collections. Equivalent to Library.deleteMember(getPath()).

Throws:

DataModelException - if the library is closed; if the member is already deleted

getPropertyNames

public String[] getPropertyNames()
                          throws DataModelException

Returns a sorted list of current property names of the object.

Returns:

a non-null String array containing property names

Throws:

DataModelException - if the library member is deleted; if the Library is closed.

hasProperty

public boolean hasProperty(String propName)
                    throws DataModelException

Tests if this member has a property of the specified name.

Parameters:

propName - name of a property (simple XML name without colon).

Returns:

true if the property exists

Throws:

DataModelException - if the library member is deleted; if the Library is closed.

getProperty

public Object getProperty(String propName)
                   throws DataModelException

Gets the value of a property by its name.

Parameters:

propName - name of a property (simple XML name without colon).

Returns:

the current value, or null if the property is not defined.

Caution: though a property can have any serializable value, some conversions are performed in setProperty.

Throws:

DataModelException - if the library member is deleted; if the Library is closed.

See Also:

setProperty(java.lang.String, java.lang.Object)

setProperty

public Object setProperty(String propName,
                          Object propValue)
                   throws DataModelException

Changes the value of a property.

Parameters:

propName - name of a property (simple XML name without colon).

propValue - the new value to set. The value can be of any serializable Java type, but some types are treated specially:

• java.lang.Float, and java.math.BigDecimal are treated as java.lang.Double, i.e converted to double, and indexed as a double. So getProperty will return java.lang.Double.
• java.lang.Integer, Short and Byte, and java.math.BigInteger are treated as Long, i.e converted to long. So getProperty will return java.lang.Long. These values are indexed (as double).
• java.lang.Boolean is treated as the type xs:boolean. It is not indexed.
• java.lang.String is always indexed.
• java.util.Date as the type xs:dateType, and indexed the same way.
• a node of the XQuery Data Model (in Qizx, the interface com.qizx.api.Node) is stored as such. Attention: DOM nodes, and other kinds of XML representations, are not recognized and not converted automatically. They have to be first converted using ItemFactory.
• Any other object is serialized and stored in binary form. No indexing is performed. Beware that usual deserialization problems might occur if the class of the object is modified.

Returns:

the former value if any, null otherwise.

Throws:

DataModelException - if the library member is deleted; if the Library is closed.

See Also:

getProperty(java.lang.String)

removeProperty

public Object removeProperty(String propName)
                      throws DataModelException

Deletes a property.

Parameters:

propName - name of a property (simple XML name without colon).

Returns:

the former value if any, null otherwise.

Throws:

DataModelException - if the library member is deleted; if the Library is closed.

getIntegerProperty

public long getIntegerProperty(String propName)
                        throws DataModelException

Convenience method: returns the integer value of a property.

Parameters:

propName - name of a property (simple XML name without colon).

Returns:

the integer value, or -1 if the property is not defined.

Throws:

DataModelException - if the library member is deleted; if the Library is closed.

setIntegerProperty

public Object setIntegerProperty(String propName,
                                 long propValue)
                          throws DataModelException

Convenience method: defines a long integer property. This is equivalent to setProperty(propName, new Long(longValue)).

Parameters:

propName - name of a property (simple XML name without colon).

propValue - long integer new value

Returns:

the former value of the property (or null if created).

Throws:

DataModelException - if the library member is deleted; if the Library is closed.