jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ju...@apache.org
Subject svn commit: r160274 - in incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi: BindableRepository.java BindableRepositoryFactory.java RegistryHelper.java
Date Wed, 06 Apr 2005 09:54:43 GMT
Author: jukka
Date: Wed Apr  6 02:54:42 2005
New Revision: 160274

URL: http://svn.apache.org/viewcvs?view=rev&rev=160274
Log:
JCR-73: Improved o.a.j.core.jndi javadocs.

Modified:
    incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepository.java
    incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepositoryFactory.java
    incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/RegistryHelper.java

Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepository.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepository.java?view=diff&r1=160273&r2=160274
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepository.java
(original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepository.java
Wed Apr  6 02:54:42 2005
@@ -35,19 +35,33 @@
 import java.io.Serializable;
 
 /**
- * <code>BindableRepository</code> ...
+ * A referenceable and serializable content repository proxy.
+ * This class implements the Proxy design pattern (GoF) for the
+ * Jackrabbit Repository implementation. The proxy implementation
+ * delays the instantiation of the actual Repository instance and
+ * implements serialization and JNDI referenceability by keeping
+ * track of the repository configuration parameters.
+ * <p>
+ * A BindableRepository instance contains the configuration file
+ * and home directory paths of a Jackrabbit repository. The separate
+ * {@link #init() init()} method is used to create a transient
+ * {@link RepositoryImpl RepositoryImpl} instance to which all the
+ * JCR API calls are delegated.
+ * <p>
+ * An instance of this class is normally always also initialized.
+ * The uninitialized state is only used briefly during the static
+ * {@link #create(String, String) create} method and during
+ * serialization and JNDI "referenciation".
  */
 class BindableRepository implements Repository, Referenceable, Serializable {
 
+    /** The serialization UID of this class. */
     static final long serialVersionUID = -2298220550793843166L;
 
-    /**
-     * path to the configuration file of the repository
-     */
+    /** The repository configuration file path. */
     private final String configFilePath;
-    /**
-     * repository home directory
-     */
+
+    /** The repository home directory path. */
     private final String repHomeDir;
 
     /**
@@ -59,14 +73,31 @@
      */
     static final String REPHOMEDIR_ADDRTYPE = "repHomeDir";
 
+    /** The delegate repository instance. Created by {@link #init() init}. */
     private transient Repository delegatee;
 
+    /**
+     * Creates a BindableRepository instance with the given configuration
+     * information, but does not create the underlying repository instance.
+     *
+     * @param configFilePath repository configuration file path
+     * @param repHomeDir repository home directory path
+     */
     private BindableRepository(String configFilePath, String repHomeDir) {
         this.configFilePath = configFilePath;
         this.repHomeDir = repHomeDir;
         delegatee = null;
     }
 
+    /**
+     * Creates an initialized BindableRepository instance using the given
+     * configuration information.
+     *
+     * @param configFilePath repository configuration file path
+     * @param repHomeDir repository home directory path
+     * @return initialized repository instance
+     * @throws RepositoryException if the repository cannot be created
+     */
     static BindableRepository create(String configFilePath, String repHomeDir)
             throws RepositoryException {
         BindableRepository rep = new BindableRepository(configFilePath, repHomeDir);
@@ -74,13 +105,21 @@
         return rep;
     }
 
+    /**
+     * Creates the underlying repository instance.
+     *
+     * @throws RepositoryException if the repository cannot be created
+     */
     private void init() throws RepositoryException {
-        RepositoryConfig config = RepositoryConfig.create(configFilePath, repHomeDir);
+        RepositoryConfig config =
+            RepositoryConfig.create(configFilePath, repHomeDir);
         delegatee = RepositoryImpl.create(config);
     }
 
     //-----------------------------------------------------------< Repository >
+
     /**
+     * Delegated to the underlying repository instance.
      * {@inheritDoc}
      */
     public Session login(Credentials credentials, String workspaceName)
@@ -89,6 +128,7 @@
     }
 
     /**
+     * Delegated to the underlying repository instance.
      * {@inheritDoc}
      */
     public Session login(String workspaceName)
@@ -97,6 +137,7 @@
     }
 
     /**
+     * Delegated to the underlying repository instance.
      * {@inheritDoc}
      */
     public Session login() throws LoginException, RepositoryException {
@@ -104,6 +145,7 @@
     }
 
     /**
+     * Delegated to the underlying repository instance.
      * {@inheritDoc}
      */
     public Session login(Credentials credentials)
@@ -112,6 +154,7 @@
     }
 
     /**
+     * Delegated to the underlying repository instance.
      * {@inheritDoc}
      */
     public String getDescriptor(String key) {
@@ -119,6 +162,7 @@
     }
 
     /**
+     * Delegated to the underlying repository instance.
      * {@inheritDoc}
      */
     public String[] getDescriptorKeys() {
@@ -126,24 +170,52 @@
     }
 
     //--------------------------------------------------------< Referenceable >
+
     /**
-     * {@inheritDoc}
+     * Creates a JNDI reference for this content repository. The returned
+     * reference holds the configuration information required to create a
+     * copy of this instance.
+     *
+     * @return the created JNDI reference
+     * @throws NamingException on JNDI errors
      */
     public Reference getReference() throws NamingException {
-        Reference ref = new Reference(BindableRepository.class.getName(),
+        Reference ref = new Reference(
+                BindableRepository.class.getName(),
                 BindableRepositoryFactory.class.getName(),
-                null);  // factory location
+                null); // no classpath defined
         ref.add(new StringRefAddr(CONFIGFILEPATH_ADDRTYPE, configFilePath));
         ref.add(new StringRefAddr(REPHOMEDIR_ADDRTYPE, repHomeDir));
         return ref;
     }
 
     //-------------------------------------------------< Serializable support >
+
+    /**
+     * Serializes the repository configuration. The default serialization
+     * mechanism is used, as the underlying delegate repository is referenced
+     * using a transient variable.
+     *
+     * @param out the serialization stream
+     * @throws IOException on IO errors
+     * @see Serializable
+     */
     private void writeObject(ObjectOutputStream out) throws IOException {
         // delegate to default implementation
         out.defaultWriteObject();
     }
 
+    /**
+     * Deserializes a repository instance. The repository configuration
+     * is deserialized using the standard deserialization mechanism, and
+     * the underlying delegate repository is created using the
+     * {@link #init() init} method.
+     *
+     * @param in the serialization stream
+     * @throws IOException if configuration information cannot be deserialized
+     *                     or if the configured repository cannot be created
+     * @throws ClassNotFoundException on deserialization errors
+     */
     private void readObject(ObjectInputStream in)
             throws IOException, ClassNotFoundException {
         // delegate deserialization to default implementation

Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepositoryFactory.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepositoryFactory.java?view=diff&r1=160273&r2=160274
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepositoryFactory.java
(original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/BindableRepositoryFactory.java
Wed Apr  6 02:54:42 2005
@@ -10,7 +10,7 @@
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
-  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

Modified: incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/RegistryHelper.java
URL: http://svn.apache.org/viewcvs/incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/RegistryHelper.java?view=diff&r1=160273&r2=160274
==============================================================================
--- incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/RegistryHelper.java
(original)
+++ incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi/RegistryHelper.java
Wed Apr  6 02:54:42 2005
@@ -21,7 +21,9 @@
 import javax.naming.NamingException;
 
 /**
- * <code>RegistryHelper</code> ...
+ * JNDI helper functionality. This class contains static utility
+ * methods for binding and unbinding Jackarbbit repositories to and
+ * from a JNDI context.
  */
 public class RegistryHelper {
 
@@ -32,6 +34,11 @@
     }
 
     /**
+     * Binds a configured repository to the given JNDI context.
+     * This method creates a {@link BindableRepository BindableRepository}
+     * instance using the given configuration information, and binds
+     * it to the given JNDI context.
+     *
      * @param ctx            context where the repository should be registered (i.e. bound)
      * @param name           the name to register the repository with
      * @param configFilePath path to the configuration file of the repository
@@ -39,8 +46,8 @@
      * @param overwrite      if <code>true</code>, any existing binding with
the given
      *                       name will be overwritten; otherwise a <code>NamingException</code>
will
      *                       be thrown if the name is already bound
-     * @throws NamingException
-     * @throws RepositoryException
+     * @throws RepositoryException if the repository cannot be created
+     * @throws NamingException if the repository cannot be registered in JNDI
      */
     public static void registerRepository(Context ctx, String name,
                                           String configFilePath,
@@ -56,9 +63,11 @@
     }
 
     /**
+     * Removes the given JNDI binding.
+     *
      * @param ctx  context where the repository should be unregistered (i.e. unbound)
      * @param name the name of the repository to unregister
-     * @throws NamingException
+     * @throws NamingException on JNDI errors
      */
     public static void unregisterRepository(Context ctx, String name)
             throws NamingException {



Mime
View raw message