hep.aida
Interface ITree

public interface ITree

User level interface to a Tree. All paths follow unix convention .., ., /, backslash is the escape character. Relative paths are allowed. NOTE: - this tree keeps a current position(pwd) within the tree. This may be implemented on a per-thread basis.

Author:

The AIDA team (http://aida.freehep.org/)

Method Summary

void	cd(String path) Change to a given directory.
void	close() Closes the underlying store.
void	commit() Commit any open transaction to the underlying store(s).
void	cp(String oldPath, String newPath) Copy an object from a path to another.
void	cp(String oldPath, String newPath, boolean recursive) Copy an object from a path to another.
IManagedObject	find(String path) Get the IManagedObject at a given path in the ITree.
String	findPath(IManagedObject object) Get the full path of an IManagedObject.
ITree	findTree(String path) Get a mounted ITree at a given path in the current ITree.
String[]	listObjectNames() Get the list of names of the IManagedObjects under a given path, including directories (but not "." and "..").
String[]	listObjectNames(String path) Get the list of names of the IManagedObjects under a given path, including directories (but not "." and "..").
String[]	listObjectNames(String path, boolean recursive) Get the list of names of the IManagedObjects under a given path, including directories (but not "." and "..").
String[]	listObjectTypes() Get the list of types of the IManagedObjects under a given path.
String[]	listObjectTypes(String path) Get the list of types of the IManagedObjects under a given path.
String[]	listObjectTypes(String path, boolean recursive) Get the list of types of the IManagedObjects under a given path.
void	ls() List, into a given output stream, all the IManagedObjects, including directories (but not "." and ".."), in a given path.
void	ls(String path) List, into a given output stream, all the IManagedObjects, including directories (but not "." and ".."), in a given path.
void	ls(String path, boolean recursive) List, into a given output stream, all the IManagedObjects, including directories (but not "." and ".."), in a given path.
void	ls(String path, boolean recursive, OutputStream os) List, into a given output stream, all the IManagedObjects, including directories (but not "." and ".."), in a given path.
void	mkdir(String path) Create a new directory.
void	mkdirs(String path) Create a directory recursively.
void	mount(String path, ITree tree, String treePath) Mounts a tree within another (target) tree.
void	mv(String oldPath, String newPath) Move an IManagedObject or a directory from one directory to another.
String	pwd() Get the path of the current working directory.
void	rm(String path) Remove an IManagedObject by specifying its path.
void	rmdir(String path) Remove a directory and all the contents underneeth.
void	setOverwrite() Set the strategy of what should happen if two objects have the same path.
void	setOverwrite(boolean overwrite) Set the strategy of what should happen if two objects have the same path.
String	storeName() Get the name of the store.
void	symlink(String path, String alias) Create a symbolic link to an object in the ITree.
void	unmount(String path) Unmount a subtree at a given path (mount point).

Method Detail

storeName

public String storeName()

Get the name of the store.

Returns:

The store's name.

find

public IManagedObject find(String path)
                    throws IllegalArgumentException

Get the IManagedObject at a given path in the ITree. The path can either be absolute or relative to the current working directory.

Parameters:

path - The path.

Returns:

The corresponding IManagedObject.

Throws:

IllegalArgumentException - If the path does not correspond to an IManagedObject.

findTree

public ITree findTree(String path)
               throws IllegalArgumentException

Get a mounted ITree at a given path in the current ITree. The path can either be absolute or relative to the current working directory.

Parameters:

path - The path.

Returns:

The corresponding ITree.

Throws:

IllegalArgumentException - If the path does not correspond to an ITree.

cd

public void cd(String path)
        throws IllegalArgumentException

Change to a given directory.

Parameters:

path - The absolute or relative path of the directory we are changing to.

Throws:

IllegalArgumentException - If the path does not exist.

pwd

public String pwd()

Get the path of the current working directory.

Returns:

The path of the current working directory.

ls

public void ls()
        throws IllegalArgumentException

List, into a given output stream, all the IManagedObjects, including directories (but not "." and ".."), in a given path. Directories end with "/". The list can be recursive. in all the directories under path (the default is false.

Throws:

IllegalArgumentException - If the path does not exist.

ls

public void ls(String path)
        throws IllegalArgumentException

List, into a given output stream, all the IManagedObjects, including directories (but not "." and ".."), in a given path. Directories end with "/". The list can be recursive.

Parameters:

path - The path where the list has to be performed (by default the current directory "."). in all the directories under path (the default is false.

Throws:

IllegalArgumentException - If the path does not exist.

ls

public void ls(String path,
               boolean recursive)
        throws IllegalArgumentException

List, into a given output stream, all the IManagedObjects, including directories (but not "." and ".."), in a given path. Directories end with "/". The list can be recursive.

Parameters:

path - The path where the list has to be performed (by default the current directory ".").

recursive - If true the list is extended recursively in all the directories under path (the default is false.

Throws:

IllegalArgumentException - If the path does not exist.

ls

public void ls(String path,
               boolean recursive,
               OutputStream os)
        throws IllegalArgumentException

List, into a given output stream, all the IManagedObjects, including directories (but not "." and ".."), in a given path. Directories end with "/". The list can be recursive.

Parameters:

path - The path where the list has to be performed (by default the current directory ".").

recursive - If true the list is extended recursively in all the directories under path (the default is false.

os - The output stream into which the list is dumped (by default the standard output).

Throws:

IllegalArgumentException - If the path does not exist.

listObjectNames

public String[] listObjectNames()
                         throws IllegalArgumentException

Get the list of names of the IManagedObjects under a given path, including directories (but not "." and ".."). Directories end with "/". The returned names are appended to the given path unless the latter is ".". in all the directories under path (the default is false.

Throws:

IllegalArgumentException - If the path does not exist.

listObjectNames

public String[] listObjectNames(String path)
                         throws IllegalArgumentException

Get the list of names of the IManagedObjects under a given path, including directories (but not "." and ".."). Directories end with "/". The returned names are appended to the given path unless the latter is ".".

Parameters:

path - The path where the list has to be performed (by default the current directory "."). in all the directories under path (the default is false.

Throws:

IllegalArgumentException - If the path does not exist.

listObjectNames

public String[] listObjectNames(String path,
                                boolean recursive)
                         throws IllegalArgumentException

Get the list of names of the IManagedObjects under a given path, including directories (but not "." and ".."). Directories end with "/". The returned names are appended to the given path unless the latter is ".".

Parameters:

path - The path where the list has to be performed (by default the current directory ".").

recursive - If true the list is extended recursively in all the directories under path (the default is false.

Throws:

IllegalArgumentException - If the path does not exist.

listObjectTypes

public String[] listObjectTypes()
                         throws IllegalArgumentException

Get the list of types of the IManagedObjects under a given path. The types are the leaf class of the Interface, e.g. "IHistogram1D", "ITuple", etc. Directories are marked with "dir". The order of the types is the same as the order for the listObjectNames() method to achieve a one-to-one correspondance between object names and types. in all the directories under path (the default is false.

Throws:

IllegalArgumentException - If the path does not exist.

listObjectTypes

public String[] listObjectTypes(String path)
                         throws IllegalArgumentException

Get the list of types of the IManagedObjects under a given path. The types are the leaf class of the Interface, e.g. "IHistogram1D", "ITuple", etc. Directories are marked with "dir". The order of the types is the same as the order for the listObjectNames() method to achieve a one-to-one correspondance between object names and types.

Parameters:

path - The path where the list has to be performed (by default the current directory "."). in all the directories under path (the default is false.

Throws:

IllegalArgumentException - If the path does not exist.

listObjectTypes

public String[] listObjectTypes(String path,
                                boolean recursive)
                         throws IllegalArgumentException

Get the list of types of the IManagedObjects under a given path. The types are the leaf class of the Interface, e.g. "IHistogram1D", "ITuple", etc. Directories are marked with "dir". The order of the types is the same as the order for the listObjectNames() method to achieve a one-to-one correspondance between object names and types.

Parameters:

path - The path where the list has to be performed (by default the current directory ".").

recursive - If true the list is extended recursively in all the directories under path (the default is false.

Throws:

IllegalArgumentException - If the path does not exist.

mkdir

public void mkdir(String path)
           throws IllegalArgumentException

Create a new directory. Given a path only the last directory in it is created if all the intermediate subdirectories already exist.

Parameters:

path - The absolute or relative path of the new directory.

Throws:

IllegalArgumentException - If a subdirectory within the path does not exist or it is not a directory. Also if the directory already exists.

mkdirs

public void mkdirs(String path)
            throws IllegalArgumentException

Create a directory recursively. Given a path the last directory and all the intermediate non-existing subdirectories are created.

Parameters:

path - The absolute or relative path of the new directory.

Throws:

IllegalArgumentException - If an intermediate subdirectory is not a directory, or if the directory already exists.

rmdir

public void rmdir(String path)
           throws IllegalArgumentException

Remove a directory and all the contents underneeth.

Parameters:

path - The absolute or relative path of the directory to be removed.

Throws:

IllegalArgumentException - If path does not exist or if it is not a directory.

rm

public void rm(String path)
        throws IllegalArgumentException

Remove an IManagedObject by specifying its path. If the path points to a mount point, the mount point should first commit, then close and delete the tree object.

Parameters:

path - The absolute or relative path of the IManagedObject to be removed.

Throws:

IllegalArgumentException - If path does not exist.

findPath

public String findPath(IManagedObject object)
                throws IllegalArgumentException

Get the full path of an IManagedObject.

Parameters:

object - The IManagedObject whose path is to be returned.

Returns:

The object's absolute path. In C++ if the object does not exist, an empty string is returned.

Throws:

IllegalArgumentException - If the IManagedObject does not exist.

mv

public void mv(String oldPath,
               String newPath)
        throws IllegalArgumentException

Move an IManagedObject or a directory from one directory to another.

Parameters:

oldPath - The path of the IManagedObject or direcoty to be moved.

newPath - The path of the diretory in which the object has to be moved to.

Throws:

IllegalArgumentException - If either path does not exist.

commit

public void commit()
            throws IOException

Commit any open transaction to the underlying store(s). It flushes objects into the disk for non-memory-mapped stores.

Throws:

IOException - If the underlying store cannot be written out.

setOverwrite

public void setOverwrite()

Set the strategy of what should happen if two objects have the same path. Default is overwrite.

setOverwrite

public void setOverwrite(boolean overwrite)

Set the strategy of what should happen if two objects have the same path. Default is overwrite.

Parameters:

overwrite - true to enable overwriting.

cp

public void cp(String oldPath,
               String newPath)
        throws IllegalArgumentException

Copy an object from a path to another.

Parameters:

oldPath - The path of the object to be copied.

newPath - The path where the object is to be copied.

Throws:

IllegalArgumentException - If either path does not exist.

cp

public void cp(String oldPath,
               String newPath,
               boolean recursive)
        throws IllegalArgumentException

Copy an object from a path to another.

Parameters:

oldPath - The path of the object to be copied.

newPath - The path where the object is to be copied.

recursive - true if a recursive copy has to be performed.

Throws:

IllegalArgumentException - If either path does not exist.

symlink

public void symlink(String path,
                    String alias)
             throws IllegalArgumentException

Create a symbolic link to an object in the ITree.

Parameters:

path - The absolute or relative path of the object to be linked.

alias - The absolute or relative name of the link.

Throws:

IllegalArgumentException - If path or any subidrectory within path does not exist.

mount

public void mount(String path,
                  ITree tree,
                  String treePath)
           throws IllegalArgumentException

Mounts a tree within another (target) tree. A tree can only be mounted once. Example:

     target.mount("/home/tonyj",tree,"/");
 

Parameters:

path - The path in the target tree

tree - The tree to mount within the target tree

treePath - The mount point within the tree to be mounted.

Throws:

IllegalArtumentException - If something does not exist.

IllegalArgumentException

unmount

public void unmount(String path)
             throws IllegalArgumentException

Unmount a subtree at a given path (mount point). Whenever a tree is destroyed it first unmounts all dependent trees.

Parameters:

path - The path of the subtree to be unmounted.

Throws:

IllegalArgumentException - If path does not exist.

close

public void close()
           throws IOException

Closes the underlying store. Changes will be saved only if commit() has been called before. The call is propagated to the dependent mounted trees.

Throws:

IOException - If there are problems writing out the underlying store.