package org.wyona.yarep.core;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Date;
/**
* This class represents a repository node.
* A repository node may be either a collection ("directory") or a resource ("file").
* If it is a resource, it has an associated data content, which may be accessed by using
* getInputStream()/getOutputStream().
* To store textual data, the reader/writer methods should be used instead of the stream
* methods to allow the implementation to handle textual data differently from binary data.
*
* @see org.wyona.yarep.core.Repository
*/
public interface Node {
/**
* Gets the name of this node, which is the last part of the path.
* @return name
* @throws RepositoryException repository error
*/
public String getName() throws RepositoryException;
/**
* Gets the parent node of this node.
* @return parent node or null if this is the root node
* @throws RepositoryException repository error
*/
public Node getParent() throws RepositoryException;
/**
* Deletes this node and all subnodes.
* The root node cannot be deleted.
* @throws RepositoryException if this node is the root node or if a repository error occurs.
*/
public void delete() throws RepositoryException;
/**
* Gets the complete repository path of this node.
* @return path
* @throws RepositoryException repository error
*/
public String getPath() throws RepositoryException;
/**
* Gets the UUID of this node.
* @return uuid
* @throws RepositoryException repository error
*/
public String getUUID() throws RepositoryException;
/**
* Gets the type of this node (collection or resource).
* @return type
* @throws RepositoryException repository error
* @see org.wyona.yarep.core.NodeType
*/
public int getType() throws RepositoryException;
/**
* Indicates whether this node is of type "resource".
* @return true if type is resource
* @throws RepositoryException repository error
*/
public boolean isResource() throws RepositoryException;
/**
* Indicates whether this node is of type "collection".
* @return true if type is collection
* @throws RepositoryException repository error
*/
public boolean isCollection() throws RepositoryException;
/**
* Indicates whether the content of this node is binary or textual.
* Useful only if this node is a resource.
* @return true if the content of this node is binary
* @throws RepositoryException repository error
*/
//public boolean isBinary() throws RepositoryException;
/**
* Creates a new node and adds it as a direct child to this node.
* @param name name of the child node
* @param type node type of the child node (e.g. collection or resource, see NodeType)
* @return the new child node
* @throws RepositoryException if this node is not a collection or if a repository error occurs
*/
public Node addNode(String name, int type) throws RepositoryException;
/**
* Gets the child node with the given name. Must be a direct child.
* @param name name of the child node
* @return child node
* @throws NoSuchNodeException if no child node with this name exists.
* @throws RepositoryException if node is not a collection or if a repository error occurs
*/
public Node getNode(String name) throws NoSuchNodeException, RepositoryException;
/**
* Gets all child nodes.
*
* There is no guarantee that the nodes in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.
*
* @return child nodes or empty array if there are no child nodes.
* @throws RepositoryException if node is not a collection or if a repository error occurs
*/
public Node[] getNodes() throws RepositoryException;
/**
* Indicates whether this node has a direct child node with the given name.
* @param name
* @return true if child node exists with the given id, false otherwise
* @throws RepositoryException if node is not a collection or if a repository error occurs
*/
public boolean hasNode(String name) throws RepositoryException;
/**
* Gets the property with the given name.
* @param name Name of property
* @return property or null if the property does not exist
* @throws RepositoryException repository error
*/
public Property getProperty(String name) throws RepositoryException;
/**
* Get all properties of this node
* @return array of properties of this node or empty array if there are no properties.
* @throws RepositoryException other error
*/
public Property[] getProperties() throws RepositoryException;
/**
* Indicates whether this node has a property with the given name.
* @param name
* @return true if a property exists with the given name, false otherwise
* @throws RepositoryException repository error
*/
public boolean hasProperty(String name) throws RepositoryException;
//public boolean hasProperties() throws RepositoryException;
/**
* Removes the property with the given name.
* Does nothing if no property with the given name exists.
* @param name
* @throws RepositoryException repository error
*/
public void removeProperty(String name) throws RepositoryException;
/**
* Sets a property of type boolean or creates it if it does not exist yet.
* @param name
* @param value
* @return the set property
* @throws RepositoryException repository error
*/
public Property setProperty(String name, boolean value) throws RepositoryException;
/**
* Sets a property of type date or creates it if it does not exist yet.
* @param name
* @param value
* @return the set property
* @throws RepositoryException repository error
*/
public Property setProperty(String name, Date value) throws RepositoryException;
/**
* Sets a property of type double or creates it if it does not exist yet.
* @param name
* @param value
* @return the set property
* @throws RepositoryException repository error
*/
public Property setProperty(String name, double value) throws RepositoryException;
//public Property setProperty(String name, InputStream value) throws RepositoryException;
/**
* Sets a property of type long or creates it if it does not exist yet.
* @param name
* @param value
* @return the set property
* @throws RepositoryException repository error
*/
public Property setProperty(String name, long value) throws RepositoryException;
/**
* Sets a property of type string or creates it if it does not exist yet.
* @param name
* @param value
* @return the set property
* @throws RepositoryException repository error
*/
public Property setProperty(String name, String value) throws RepositoryException;
/**
* Sets a property or creates it if it does not exist yet.
* @param property
* @throws RepositoryException repository error
*/
public void setProperty(Property property) throws RepositoryException;
//public Property getDefaultProperty() throws RepositoryException;
/**
* Gets an input stream of the binary data content of this node.
* Useful only for nodes of type resource.
* @return input stream
* @throws RepositoryException repository error
*/
public InputStream getInputStream() throws RepositoryException;
//public void setInputStream(InputStream inputStream) throws RepositoryException;
/**
* Gets an output stream of the binary data content of this node.
* Useful only for nodes of type resource.
* Don't forget to close the stream because some implementations may
* require that.
* @return output stream
* @throws RepositoryException repository error
*/
public OutputStream getOutputStream() throws RepositoryException;
/**
* Puts this node into checked-in state and creates a new revision.
* @return the new revision
* @throws NodeStateException if node is not in checked out state
* @throws RepositoryException repository error
*/
public Revision checkin() throws NodeStateException, RepositoryException;
/**
* Puts this node into checked-in state and creates a new revision.
* @param comment a comment to add to the new revision.
* @return the new revision
* @throws NodeStateException if node is not in checked out state
* @throws RepositoryException repository error
*/
public Revision checkin(String comment) throws NodeStateException, RepositoryException;
/**
* Puts this node into checked-out state.
* @throws NodeStateException if node is in checked out state already
* @throws RepositoryException repository error
*/
public void checkout(String userID) throws NodeStateException, RepositoryException;
/**
* Cancels a checkout, i.e. performs a checkin without creating a new revision.
* @throws NodeStateException
* @throws NodeStateException if node is not in checked out state
* @throws RepositoryException
*/
public void cancelCheckout() throws NodeStateException, RepositoryException;
/**
* Indicates whether this node is checked out.
* @return true if checked out, false otherwise
* @throws RepositoryException repository error
*/
public boolean isCheckedOut() throws RepositoryException;
/**
* Gets the userID which was supplied when calling checkout(userID).
* @return userID
* @throws NodeStateException if node is not checked out.
* @throws RepositoryException
*/
public String getCheckoutUserID() throws NodeStateException, RepositoryException;
/**
* Gets the date when this node was checked out.
* @return checkout date
* @throws NodeStateException if node is not checked out.
* @throws RepositoryException
*/
public Date getCheckoutDate() throws NodeStateException, RepositoryException;
/**
* Gets the date when this node was checked in.
* @return checkin date
* @throws NodeStateException if node is not checked in.
* @throws RepositoryException
*/
public Date getCheckinDate() throws NodeStateException, RepositoryException;
/**
* Gets all revisions of this node.
* Oldest revision at the first array position, newest at the last position.
* @return array of revisions, or empty array if there are no revisions
* @throws RepositoryException
*/
public Revision[] getRevisions() throws RepositoryException;
/**
* Gets the revision with the given name.
* @param revisionName
* @return revision
* @throws NoSuchRevisionException if the revision does not exist
* @throws RepositoryException
*/
public Revision getRevision(String revisionName) throws NoSuchRevisionException, RepositoryException;
/**
* Gets the revision with the given tag.
* If multiple revisions have the same tag, the oldest one will be returned.
* @param tag
* @return revision
* @throws NoSuchRevisionException if the revision does not exist
* @throws RepositoryException
*/
public Revision getRevisionByTag(String tag) throws NoSuchRevisionException, RepositoryException;
/**
* Indicates whether this node has a revision with the given tag.
* If multiple revisions have the same tag, the oldest one will be returned.
* @param tag
* @return true if a revision with the given tag exists, false otherwise
* @throws RepositoryException
*/
public boolean hasRevisionWithTag(String tag) throws RepositoryException;
/**
* Restores the revision with the given name.
* @param revisionName
* @throws NoSuchRevisionException if the revision does not exist
* @throws RepositoryException
*/
public void restore(String revisionName) throws NoSuchRevisionException, RepositoryException;
/**
* Gets the last modified date of this node in ms.
* Changing a property should update the last modified date.
* @return last modified date in ms
* @throws RepositoryException
*/
public long getLastModified() throws RepositoryException;
/**
* Gets the size of the data content of this node if this node is of type resource.
* @return size in bytes
* @throws RepositoryException
*/
public long getSize() throws RepositoryException;
/**
* Gets the mimetype of the data content of this node if this node is of type resource.
* @return mimetype
* @throws RepositoryException
*/
public String getMimeType() throws RepositoryException;
/**
* Sets the mimetype of the data content of this node if this node is of type resource.
* @param mimeType
* @throws RepositoryException
*/
public void setMimeType(String mimeType) throws RepositoryException;
/**
* Gets the encoding of the data content of this node if this node is of type resource.
* @return encoding
* @throws RepositoryException
*/
public String getEncoding() throws RepositoryException;
/**
* Sets the encoding of the data content of this node if this node is of type resource.
* @param encoding
* @throws RepositoryException
*/
public void setEncoding(String encoding) throws RepositoryException;
}