You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by ju...@apache.org on 2005/04/06 11:54:43 UTC
svn commit: r160274 - in
incubator/jackrabbit/trunk/src/java/org/apache/jackrabbit/core/jndi:
BindableRepository.java BindableRepositoryFactory.java RegistryHelper.java
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 {