Qizx fe-4.4p2 API

com.qizx.api
Interface LibraryMember

All Known Subinterfaces:
Collection, Document, NonXMLDocument

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 NONXMLDOC
          Value of the predefined property 'nature' for a non-XML Document, equal to "non-xml".
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 (XML or non-XML).
 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

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

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

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

See Also:
Constant Field Values

DOCUMENT

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

See Also:
Constant Field Values

NONXMLDOC

static final String NONXMLDOC
Value of the predefined property 'nature' for a non-XML Document, equal to "non-xml".

See Also:
Constant Field Values
Method Detail

getLibrary

Library getLibrary()
Returns the Library session owning this member.

Returns:
a Library session

exists

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

Returns:
true if the member actually exists

isCollection

boolean isCollection()
Returns true if the member is a Collection.

Returns:
true if the member is a Collection.

isDocument

boolean isDocument()
Returns true if the member is a Document (XML or non-XML).

Returns:
true if the member is a Document.

getPath

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

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

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

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

contains

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

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

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

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

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

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

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

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

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 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.
  • An Item created using ItemFactory.createItem(java.lang.Object, com.qizx.api.ItemType). The item can be cast to one of types supported by properties: boolean, long, double, date, string.
  • 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

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

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

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.

© 2010 Axyana Software