org.exist.fluent
Class Folder

java.lang.Object
  org.exist.fluent.Resource
      org.exist.fluent.NamedResource
          org.exist.fluent.Folder

All Implemented Interfaces:

Cloneable

public class Folder
extends NamedResource
implements Cloneable

A named collection of XML documents in the database. Each document belongs to precisely one folder. Folders can be nested, with queries carried out within either the scope of a single folder or of a whole subtree.

Though the name Collection is commonly used for these constructs in the context of XML databases, the name Folder was chosen instead to avoid conflicting with the ubiquitous Java java.util.Collection interface.

Instances of this class are not thread-safe.

Version:

$Revision: 1.31 $ ($Date: 2006/09/04 06:09:05 $)

Author:

Piotr Kaminski

Nested Class Summary

class	Folder.ChildrenFacet The children (subfolders) facet of a collection.
class	Folder.DocumentsFacet The immediate documents facet of a folder.
static class	Folder.Event An event that concerns a folder.
static interface	Folder.Listener Listener for events affecting folders.
class	Folder.ListenersFacet The facet that allwos control over listeners to the folder, and all its descendant folders and documents.

Nested classes/interfaces inherited from class org.exist.fluent.NamedResource

NamedResource.MetadataFacet

Method Summary

Folder.ChildrenFacet	children() Return the children facet of this folder that gives access to operations on its subfolders and descendants.
void	clear() Remove all resources and subfolders from this folder, but keep the folder itself.
Folder	clone() Create a duplicate handle that copies the original's path and namespace bindings.
Folder	cloneWithoutNamespaceBindings()
boolean	contains(NamedResource res) Return whether this folder or one of its descendants contains the given named resource.
Folder	copy(Folder destination, Name name) Copy this folder to another place in the folder hierarchy, returning the newly copied folder with namespace bindings inherited from this one.
void	delete() Delete this folder, including all documents and descendants.
Folder.DocumentsFacet	documents() Provide access to the documents facet of this folder.
boolean	equals(Object o)
void	export(File destination) Export the contents of this folder (both documents and subfolders) to the given directory.
int	hashCode()
boolean	isEmpty() Return whether this folder is empty, i.e.
Folder.ListenersFacet	listeners() Return this folder's listeners facet, giving control over listeners to events on this folder, its contents, and all its descendants.
NamedResource.MetadataFacet	metadata() Return the metadata facet for this resource, which lets you read and manipulate metadata such as ownership, access permissions, and creation/modification timestamps.
void	move(Folder destination, Name name) Move this folder to another spot in the folder hierarchy, possibly changing its name in the process.
String	name() Return the local name of the folder; this is the last segment of its path.
Folder	parent() Return the parent folder of this folder.
String	path() Return the full path to the folder; always starts with '/'.
QueryService	query() Return a query service for executing queries over the contents of this folder and the contents of all its descendants.
String	relativePath(String subPath) Return the given path stripped of this folder's prefix path, i.e.
String	toString()

Methods inherited from class org.exist.fluent.Resource

database, namespaceBindings

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

listeners

public Folder.ListenersFacet listeners()

Return this folder's listeners facet, giving control over listeners to events on this folder, its contents, and all its descendants.

Returns:

this folder's listeners facet

metadata

public NamedResource.MetadataFacet metadata()

Description copied from class: NamedResource

Return the metadata facet for this resource, which lets you read and manipulate metadata such as ownership, access permissions, and creation/modification timestamps.

Specified by:

metadata in class NamedResource

Returns:

the metadata facet for this resource

clone

public Folder clone()

Create a duplicate handle that copies the original's path and namespace bindings. No copy is created of the underlying folder. The namespace bindings will copy the original's immediate namespace map and namespace bindings inheritance chain.

Overrides:

clone in class Object

Returns:

a duplicate of this collection wrapper

cloneWithoutNamespaceBindings

public Folder cloneWithoutNamespaceBindings()

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

isEmpty

public boolean isEmpty()

Return whether this folder is empty, i.e. has no documents or subfolders in it.

Returns:

whether this folder is empty

clear

public void clear()

Remove all resources and subfolders from this folder, but keep the folder itself.

delete

public void delete()

Delete this folder, including all documents and descendants. If invoked on the root folder, deletes all documents and descendants but does not delete the root folder itself.

Specified by:

delete in class NamedResource

move

public void move(Folder destination,
                 Name name)

Move this folder to another spot in the folder hierarchy, possibly changing its name in the process. This folder will refer to the newly relocated folder when this method returns. You can use this method to move a folder without changing its name (folder.move(destFolder, Name.keepCreate())) or to rename it without changing its location (folder.move(folder.parent(), Name.create(newName))).

Specified by:

move in class NamedResource

Parameters:

destination - the new parent folder of this folder

name - the new name for this folder

copy

public Folder copy(Folder destination,
                   Name name)

Copy this folder to another place in the folder hierarchy, returning the newly copied folder with namespace bindings inherited from this one.

Specified by:

copy in class NamedResource

Parameters:

destination - the desired parent folder of the copy

name - the desired name of the copy

Returns:

a reference to the copied folder

documents

public Folder.DocumentsFacet documents()

Provide access to the documents facet of this folder. The documents facet is the conceptual set of documents contained directly in this collection (and therefore excludes documents contained in any subfolders).

Returns:

the documents facet

contains

public boolean contains(NamedResource res)

Return whether this folder or one of its descendants contains the given named resource.

Parameters:

res - the resource to check for

Returns:

true if the resource is contained (directly or indirectly) in this folder, false otherwise

relativePath

public String relativePath(String subPath)

Return the given path stripped of this folder's prefix path, i.e. relative to this folder. The given path can be either to a document or to a subfolder. If the given path is to this folder itself, return the empty string.

Parameters:

subPath - the path to relativize

Returns:

the given path relative to this folder

path

public String path()

Return the full path to the folder; always starts with '/'.

Specified by:

path in class NamedResource

Returns:

the full path to the folder

name

public String name()

Return the local name of the folder; this is the last segment of its path.

Specified by:

name in class NamedResource

Returns:

the local name of the folder

parent

public Folder parent()

Return the parent folder of this folder. It will inherit this folder's namespace bindings.

Returns:

the parent folder that this folder is a child of

Throws:

DatabaseException - if this is the root folder

children

public Folder.ChildrenFacet children()

Return the children facet of this folder that gives access to operations on its subfolders and descendants.

Returns:

the children facet of this folder

export

public void export(File destination)
            throws IOException

Export the contents of this folder (both documents and subfolders) to the given directory. If the directory does not exist it will be created. Documents in this folder will appear directly in the given directory, i.e. a subdirectory matching this folder will not be created.

Parameters:

destination - the destination folder to export into

Throws:

IOException - if the export failed due to an I/O error

query

public QueryService query()

Return a query service for executing queries over the contents of this folder and the contents of all its descendants. If you only want to query the documents contained directly in this folder, see the documents facet.

Overrides:

query in class Resource

Returns:

a query service over this folder's contents and all its descendants' contents