001: /*
002: * %W% %E%
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package com.sun.jump.module.contentstore;
028:
029: import com.sun.jump.module.JUMPModule;
030:
031: import java.io.IOException;
032:
033: /**
034: * <code>JUMPStore</code> provides methods to access a persistant store. The
035: * abstraction provided by the store is a hierarchical tree structure
036: * (very similar to a file system), where nodes in the tree could contain
037: * other nodes (like a directory in a file system) or contain data
038: * (like files in a file system). Every node in the store is identified
039: * using a unique URI. The root of the store is identified by ".".
040: * <p>
041: * The following code shows how the store can be used to save an
042: * application's title through <code>JUMPStoreHandle</code>.
043: * <pre>
044: * JUMPStoreHandle storeHandle;
045: * JUMPData titleData = new JUMPData("Sample App1");
046: * storeHandle.createNode("./apps/App1"); // cause JUMPStore.createNode
047: * storeHandle.createDataNode("./apps/App1/title", titleData); // cause JUMPStore.createDataNode
048: * </pre>
049: * <p>
050: * All access to the store is controlled by higher level entities like
051: * repositories, through a subclass of <code>JUMPContentStore</code>.
052: * <p>
053: * The JUMP content store API limits the URI String
054: * to use the character set of [a--z] + [0--9] for the node name.
055: * The node string should appear in the unique format; the use of "." and ".."
056: * is prohibited except for "." as the first character representing the root.
057: * The String is treated as case insensitive, "/" as a path element separator,
058: * and the use of a trailing "/" character is not allowed for both the list
059: * and the data node (ex. "./a/b/" or "./").
060: */
061: public abstract class JUMPStore implements JUMPModule {
062: /**
063: * Create a <code>JUMPNode.Data</code> identified by this url in the store.
064: * The node contains this <code>JUMPData</code>. The method should behave in an
065: * atomic fashion, i.e either the data node is created completely
066: * or nothing at all. All the elements of the <i>URI</i> except for the
067: * part that represents the leaf node must
068: * exist within the store for this call to succeed. This does not
069: * create any intermediate nodes specified in the URI, if they do not
070: * exist. If the node represented by the URI already exists, then the method
071: * also fails.
072: *
073: * @exception IOException if the node creation fails.
074: * @exception IllegalArgumentException if the URI format is invalid.
075: * @exception JUMPStoreRuntimeException if the node represented by the URI already exists.
076: */
077:
078: protected abstract void createDataNode(String uri, JUMPData data)
079: throws IOException;
080:
081: /**
082: * Create a <code>JUMPNode.List</code> identified by this URI in the store.
083: * If any of the intermediate nodes does not exist yet, then this
084: * method creates those intermediate nodes.
085: *
086: * @exception IOException if the node creation fails.
087: * @exception IllegalArgumentException if the URI format is invalid.
088: * @exception JUMPStoreRuntimeException if the node represented by the URI already exists.
089: */
090: protected abstract void createNode(String uri) throws IOException;
091:
092: /**
093: * Returns the node that is bound to the URI or null if no such node
094: * exists.
095: *
096: * @exception IOException if internal error occurs while retrieving the data.
097: * @exception IllegalArgumentException if the URI format is invalid.
098: */
099: protected abstract JUMPNode getNode(String uri) throws IOException;
100:
101: /**
102: * Delete the node pointed to by the URI. If there are child nodes under
103: * this URI, then they are deleted as well.
104: *
105: * @exception IOException if the node deletion fails
106: * @exception IllegalArgumentException if the URI format is invalid.
107: * @exception JUMPStoreRuntimeException if the URI does not point to an existing node.
108: */
109: protected abstract void deleteNode(String uri) throws IOException;
110:
111: /**
112: * Update the data associated with the URI. The method can fail in the
113: * following cases
114: * <ul>
115: * <li>URI does not exist</li>
116: * <li>URI does not point to a <Code>JUMPNode.Data</code></li>
117: * </ul>
118: * If the data cannot be updated, then the previous data in the node
119: * MUST be preserved.
120: *
121: * @exception IOException if the node update fails.
122: * @exception IllegalArgumentException if the URI format is invalid.
123: * @exception JUMPStoreRuntimeException if the URI does not exist or is not pointing to <code>JUMPNode.Data</code>
124: */
125: protected abstract void updateDataNode(String uri, JUMPData data)
126: throws IOException;
127: }
|