cmlenz 01/10/23 06:03:28
Modified: src/share/org/apache/slide/common Domain.java Namespace.java
NamespaceAccessToken.java SlideToken.java
Added: src/share/org/apache/slide/common/doc-files architecture.png
stores.png transactions.png
Log:
Copied some documentation from the website into the JavaDoc comments of the
corresponding classes, some additions and edits of the original text
included.
Also added smaller versions of some of the images in docs/images, which
will be referenced from the forthcoming overview.html.
Revision Changes Path
1.31 +69 -7 jakarta-slide/src/share/org/apache/slide/common/Domain.java
Index: Domain.java
===================================================================
RCS file: /home/cvs/jakarta-slide/src/share/org/apache/slide/common/Domain.java,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -r1.30 -r1.31
--- Domain.java 2001/09/24 01:44:35 1.30
+++ Domain.java 2001/10/23 13:03:27 1.31
@@ -1,7 +1,7 @@
/*
- * $Header: /home/cvs/jakarta-slide/src/share/org/apache/slide/common/Domain.java,v
1.30 2001/09/24 01:44:35 remm Exp $
- * $Revision: 1.30 $
- * $Date: 2001/09/24 01:44:35 $
+ * $Header: /home/cvs/jakarta-slide/src/share/org/apache/slide/common/Domain.java,v
1.31 2001/10/23 13:03:27 cmlenz Exp $
+ * $Revision: 1.31 $
+ * $Date: 2001/10/23 13:03:27 $
*
* ====================================================================
*
@@ -85,13 +85,75 @@
import org.xml.sax.helpers.*;
/**
- * Domain class.
+ * The Domain controls access to its registered namespaces and performs
+ * initialization and connection management on behalf of the namespaces.
+ *
+ * <p>
+ * From the client application's perspective, the domain represents the only
+ * directly accessible object. It is through this object that the client
+ * gains access to namespaces, using the static method
+ * <code>Domain.accessNamespace()</code>.
* <p/>
- * For now, does not implement access control on Namespaces.
- *
+ * <p>
+ * Since the domain acts as the root of a directory service, it is a static
+ * entity and there can be only one domain per JVM.
+ * </p>
+ * <h3>Initialization</h3>
+ * <p>
+ * When Slide is first initialized, the Domain configuration is loaded.
+ * The location of the domain configuration file is given through the
+ * <code>org.apache.slide.domain</code> property in the Slide properties, or
+ * can be specified as argument to the static <code>Domain.init()</code>
+ * method.
+ * </p>
+ * <p>
+ * The domain configuration is written by an administrator and describes how
+ * each namespace is to be initialized. It includes information like:
+ * <ul>
+ * <li>
+ * The low-level services the namespace uses (structure store, content
+ * store, etc.)
+ * </li>
+ * <li>
+ * The namespace base topology, which includes the location of the base
+ * actions and paths in the namespace.
+ * </li>
+ * </ul>
+ * </p>
+ * <h3>Access and Security</h3>
+ * <p>
+ * After initialization is complete, the client application can request
+ * access to the domain. It uses one of the two methods:
+ * <ul>
+ * <li>
+ * {@link #accessNamespace Domain.accessNamespace(SecurityToken
+ securityObject, String namespace)}
+ * <br>
+ * Used to access a specific namespace. This method returns a
+ * <code>NamespaceAccessToken</code>, which thereafter must be used by
+ * the client application to perform operations on the namespace.
+ * <br><br>
+ * </li>
+ * <li>
+ * {@link #accessDomain Domain.accessDomain(SecurityToken
+ securityObject)}
+ * <br>
+ * Enumerates the registered namespaces with this domain. This allows
+ * application to browse the list of available namespaces.
+ * </li>
+ * </ul>
+ * </p>
+ * <p>
+ * The Domain uses an object (argument <code>securityObject</code>) to
+ * decide whether or not the client should be granted access. A good
+ * candidate is a reference to the client servlet or servlet context.<br><br>
+ * <i><small>Note: Currently, access control on namespaces is not
+ * implemented.</small></i>
+ * </p>
+ *
* @author <a href="mailto:[EMAIL PROTECTED]";>Remy Maucherat</a>
* @author Dirk Verbeeck
- * @version $Revision: 1.30 $
+ * @version $Revision: 1.31 $
*/
public final class Domain {
1.41 +37 -6 jakarta-slide/src/share/org/apache/slide/common/Namespace.java
Index: Namespace.java
===================================================================
RCS file: /home/cvs/jakarta-slide/src/share/org/apache/slide/common/Namespace.java,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- Namespace.java 2001/10/03 21:27:45 1.40
+++ Namespace.java 2001/10/23 13:03:27 1.41
@@ -1,7 +1,7 @@
/*
- * $Header:
/home/cvs/jakarta-slide/src/share/org/apache/slide/common/Namespace.java,v 1.40
2001/10/03 21:27:45 remm Exp $
- * $Revision: 1.40 $
- * $Date: 2001/10/03 21:27:45 $
+ * $Header:
/home/cvs/jakarta-slide/src/share/org/apache/slide/common/Namespace.java,v 1.41
2001/10/23 13:03:27 cmlenz Exp $
+ * $Revision: 1.41 $
+ * $Date: 2001/10/23 13:03:27 $
*
* ====================================================================
*
@@ -90,11 +90,42 @@
import org.apache.slide.util.logger.Logger;
/**
- * Namespace class.
- *
+ * A Namespace contains a hierarchically organized tree of information.
+ *
+ * <p>
+ * Objects in the namespace are generally referred to as <i>Nodes</i>. Nodes
+ * may have a parent, children, content and meta-data. They can also be
+ * versioned (so that multiple revisions of the object's content and
+ * metadata are stored) and locked (so that only specific principals are
+ * allowed to read or modify the object). In addition, access control
+ * information can be assigned to every node.
+ * </p>
+ * <p>
+ * Nodes in the hierarchy are identified by their URI (Unique Resource
+ * Identifier). A URI is analogous to a file path in traditional file
+ * systems. For example:
+ * <pre>
+ * /users/john/documents/my_document.txt
+ * </pre>
+ * As you can see, the slash ("/") is used to separate nodes in the
path.
+ * </p>
+ * <p>
+ * Client applications can not access a Namespace object directly. Instead,
+ * access must be requested from the {@link Domain Domain}, which will hand
+ * out a proxy object ({@link NamespaceAccessToken NamespaceAccessToken})
+ * that enables the client application to access the namespace using the
+ * helpers.
+ * </p>
+ * <p>
+ * Namespaces are necessarily self-contained. What this means is that a
+ * namespace cannot reference or contain links to another namespace. A
+ * namespace is typically assigned per-application, which effectively
+ * isolates it's data and security context from those of other applications.
+ * </p>
+ *
* @author <a href="mailto:[EMAIL PROTECTED]";>Remy Maucherat</a>
* @author Dirk Verbeeck
- * @version $Revision: 1.40 $
+ * @version $Revision: 1.41 $
*/
public final class Namespace {
1.13 +19 -5
jakarta-slide/src/share/org/apache/slide/common/NamespaceAccessToken.java
Index: NamespaceAccessToken.java
===================================================================
RCS file:
/home/cvs/jakarta-slide/src/share/org/apache/slide/common/NamespaceAccessToken.java,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- NamespaceAccessToken.java 2001/06/20 18:16:58 1.12
+++ NamespaceAccessToken.java 2001/10/23 13:03:27 1.13
@@ -1,7 +1,7 @@
/*
- * $Header:
/home/cvs/jakarta-slide/src/share/org/apache/slide/common/NamespaceAccessToken.java,v
1.12 2001/06/20 18:16:58 remm Exp $
- * $Revision: 1.12 $
- * $Date: 2001/06/20 18:16:58 $
+ * $Header:
/home/cvs/jakarta-slide/src/share/org/apache/slide/common/NamespaceAccessToken.java,v
1.13 2001/10/23 13:03:27 cmlenz Exp $
+ * $Revision: 1.13 $
+ * $Date: 2001/10/23 13:03:27 $
*
* ====================================================================
*
@@ -97,10 +97,24 @@
import org.apache.slide.util.logger.Logger;
/**
- * Namespace access token interface.
+ * The <code>NamespaceAccessToken</code> is an interface used to completely
+ * hide the real {@link Namespace Namespace} object reference from the client
+ * application. It is used by Slide to authenticate and control any operations
+ * on the namespace.
*
+ * <p>
+ * Using the NamespaceAccessToken, the application can obtain access to the
+ * helper interfaces (<code>Content</code>, <code>Lock</code>,
+ * <code>Macro</code>, <code>Security</code> and <code>Structure</code>).
+ * </p>
+ * <p>
+ * The NamespaceAccessToken object implements the <tt>UserTransaction</tt>
+ * interface (see the Java Transaction API documentation for more details)
+ * to allow the client to control transaction demarcation.
+ * </p>
+ *
* @author <a href="mailto:[EMAIL PROTECTED]";>Remy Maucherat</a>
- * @version $Revision: 1.12 $
+ * @version $Revision: 1.13 $
*/
public interface NamespaceAccessToken extends UserTransaction {
1.7 +26 -5 jakarta-slide/src/share/org/apache/slide/common/SlideToken.java
Index: SlideToken.java
===================================================================
RCS file: /home/cvs/jakarta-slide/src/share/org/apache/slide/common/SlideToken.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- SlideToken.java 2001/09/10 09:20:56 1.6
+++ SlideToken.java 2001/10/23 13:03:27 1.7
@@ -1,7 +1,7 @@
/*
- * $Header:
/home/cvs/jakarta-slide/src/share/org/apache/slide/common/SlideToken.java,v 1.6
2001/09/10 09:20:56 juergen Exp $
- * $Revision: 1.6 $
- * $Date: 2001/09/10 09:20:56 $
+ * $Header:
/home/cvs/jakarta-slide/src/share/org/apache/slide/common/SlideToken.java,v 1.7
2001/10/23 13:03:27 cmlenz Exp $
+ * $Revision: 1.7 $
+ * $Date: 2001/10/23 13:03:27 $
*
* ====================================================================
*
@@ -69,9 +69,29 @@
import org.apache.slide.authenticate.CredentialsToken;
/**
- * Slide token class.
- *
+ * The SlideToken interface identifies the current acting principal and its
+ * credentials, and maintains information about the state of the user
+ * transaction.
+ *
+ * <p>
+ * An object implementing this interface is required to use any of the
+ * methods provided by the helpers API. The default implementation of this
+ * interface is {@link SlideTokenImpl SlideTokenImpl}. In the context of a
+ * Java servlet, such an object should be instantiated like this:
+ * <pre>
+ * Principal principal = request.getUserPrincipal();
+ * CredentialsToken credentials;
+ * if (principal == null) {
+ * credentials = new CredentialsToken("");
+ * } else {
+ * credentials = new CredentialsToken(principal);
+ * }
+ * SlideToken token = new SlideTokenImpl(credentials);
+ * </pre>
+ * </p>
+ *
* @author <a href="mailto:[EMAIL PROTECTED]";>Remy Maucherat</a>
+ * @version $Revision: 1.7 $
*/
public interface SlideToken {
@@ -209,3 +229,4 @@
}
+
1.1
jakarta-slide/src/share/org/apache/slide/common/doc-files/architecture.png
<<Binary file>>
1.1
jakarta-slide/src/share/org/apache/slide/common/doc-files/stores.png
<<Binary file>>
1.1
jakarta-slide/src/share/org/apache/slide/common/doc-files/transactions.png
<<Binary file>>
