JCR-5262: convert package.html to package-info.java

jackrabbit-core/src/main/java/org/apache/jackrabbit/core/config/package-info.java

@@ -0,0 +1,73 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ *
+ * Jackrabbit configuration handling.
+ * <p>
+ * This package contains functionality for reading and manipulating the
+ * Jackrabbit configuration. The configuration functionality can be
+ * divided in two parts: parsing and representing configuration.
+ *
+ * <h2>Parsing configuration</h2>
+ * <p>
+ * The configuration parsing functionality is located in the
+ * {@link org.apache.jackrabbit.core.config.ConfigurationParser ConfigurationParser}
+ * class. The parser class reads repository and workspace configuration
+ * files and builds corresponding configuration object structures.
+ * <p>
+ * <p>
+ * The static <code>create()</code> factory methods of the
+ * {@link org.apache.jackrabbit.core.config.RepositoryConfig RepositoryConfig}
+ * class are the standard ways of invoking the configuration parser.
+ * </p>
+ *
+ * <h2>Representating configuration</h2>
+ * <p>
+ * The parsed configuration information is represented using Config object
+ * structures. The
+ * {@link org.apache.jackrabbit.core.config.RepositoryConfig RepositoryConfig}
+ * and
+ * {@link org.apache.jackrabbit.core.config.WorkspaceConfig WorkspaceConfig}
+ * classes are used for the top-level configuration. Other configuration classes
+ * are used according to the class diagram shown below.
+ * <img src="doc-files/class.jpg" alt="Class Diagram for Repository Configuration">
+ * <p>
+ * In addition to the static configuration information, some Config classes
+ * contain references to configured implementation objects. These implementation
+ * objects are not instantiated in the Config constructors to simplify
+ * configuration parsing. Instead the Config classes provide an
+ * <code>init()</code> method that instantiates and initializes all
+ * contained implementation objects.
+ * <p>
+ * The
+ * {@link org.apache.jackrabbit.core.config.RepositoryConfig RepositoryConfig}
+ * class contains also a set of static and instance methods for manipulating
+ * the repository configuration, especially creating and loading workspace
+ * configurations.
+ *
+ * <h2>Modifying configuration</h2>
+ * <p>
+ * The configuration classes in this package are immutable to enforce the
+ * contract that the configuration should not be modified once it has been
+ * intstantiated. It is possible to subclass the configuration classes as long
+ * as the immutability contract is not broken. The public constructors allow
+ * a limited form of dynamic configurability for Jackrabbit, but note that the
+ * only officially supported Jackrabbit configuration interface are the XML
+ * configuration files.
+ * </p>
+ */
+package org.apache.jackrabbit.core.config;

jackrabbit-core/src/main/java/org/apache/jackrabbit/core/fs/db/package-info.java

@@ -0,0 +1,35 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ *
+ * This package contains the class <code>{@link DbFileSystem}</code>,
+ * a simple generic JDBC-based <code>FileSystem</code> implementation
+ * for Jackrabbit.
+ * <p>
+ * It also contains [schemaName].ddl files which are read by
+ * <code>{@link DbFileSystem}</code>  in order to automatically
+ * create the required schema objects on the target database. Every line in a
+ * [schemaName].ddl file is executed separatly by calling
+ * <code>java.sql.Statement.execute(String)</code> where every occurence of the
+ * the string <code>"${schemaObjectPrefix}"</code> has been replaced with the
+ * value of the property <code>schemaObjectPrefix</code> (see
+ * <code>{@link DbFileSystem#setSchemaObjectPrefix(String)}</code>).
+ * The schema name is either set programmtically by calling
+ * <code>{@link DbFileSystem#setSchema(String)}</code> or configured
+ * through the <code>schema</code> bean property.
+ */
+package org.apache.jackrabbit.core.fs.db;

jackrabbit-core/src/main/java/org/apache/jackrabbit/core/package-info.java

@@ -0,0 +1,116 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ *
+ * Contains the core classes that provide the implementation of the JCR API.
+ * <p>
+ * The following table lists the core JCR interfaces and the corresponding
+ * Jackrabbit implementation classes found in this package.
+ * <table>
+ * <caption>JCR interfaces and Jackrabbit implementations</caption>
+ * <thead>
+ * <tr>
+ * <th>JCR interface</th>
+ * <th>Implementation class</th>
+ * </tr>
+ * </thead>
+ * <tbody>
+ * <tr>
+ * <td>{@link javax.jcr.Repository Repository}</td>
+ * <td>{@link org.apache.jackrabbit.core.RepositoryImpl RepositoryImpl}</td>
+ * </tr>
+ * <tr>
+ * <td>{@link javax.jcr.Session Session}</td>
+ * <td>{@link org.apache.jackrabbit.core.SessionImpl SessionImpl}</td>
+ * </tr>
+ * <tr>
+ * <td>{@link javax.jcr.Workspace Workspace}</td>
+ * <td>{@link org.apache.jackrabbit.core.WorkspaceImpl WorkspaceImpl}</td>
+ * </tr>
+ * <tr>
+ * <td>{@link javax.jcr.Item Item}</td>
+ * <td>{@link org.apache.jackrabbit.core.ItemImpl ItemImpl}</td>
+ * </tr>
+ * <tr>
+ * <td>{@link javax.jcr.Property Property}</td>
+ * <td>{@link org.apache.jackrabbit.core.PropertyImpl PropertyImpl}</td>
+ * </tr>
+ * <tr>
+ * <td>{@link javax.jcr.Node Node}</td>
+ * <td>{@link org.apache.jackrabbit.core.NodeImpl NodeImpl}</td>
+ * </tr>
+ * </tbody>
+ * </table>
+ * <p>
+ * A Jackrabbit repository instance can be created using the static
+ * {@link org.apache.jackrabbit.core.RepositoryImpl#create(org.apache.jackrabbit.core.config.RepositoryConfig) RepositoryImpl.create(RepositoryConfig)}
+ * method. Classes in the
+ * {@link org.apache.jackrabbit.core.jndi org.apache.jackrabbit.core.jndi}
+ * package provide a mechanism for binding a Jackrabbit repository in a
+ * JNDI directory context.
+ * <p>
+ * A <code>SessionImpl</code> instance is created upon successfully login to the
+ * <code>Repository</code> (see <code>Repository#login(Credentials, String)</code>).
+ * <p>
+ * A <code>Session</code> is always tied to the <code>Workspace</code>
+ * specified in the <code>Repository#login(Credentials, String)</code> call. A
+ * workspace represents a persistent tree of repository items (i.e. <code>Node</code>s
+ * and <code>Property</code>s). The items in a workspace are 'visible' to all
+ * sessions accessing it (subject to their access rights, of course).
+ * A <code>WorkspaceImpl</code> instance represents a specifc workspace as
+ * seen by the session that accesses it.
+ * <p>
+ * Every repository item is uniquely identified by its <code>ItemId</code>. The id
+ * of a node (<code>NodeId</code>) consists of the node's uuid. The id of a property
+ * (<code>PropertyId</code>) consists of the parent node's uuid and the
+ * name of the property.
+ *
+ * <h2>Item managers</h2>
+ * <p>
+ * Every <code>SessionImpl</code> instance has its own <code>ItemManager</code>.
+ * The per-session instance of <code>ItemManager</code> acts as item factory (i.e.
+ * it creates <code>NodeImpl</code> and <code>PropertyImpl</code> instances) and
+ * provides item access by item id and item caching.
+ * <p>
+ * The data (or state) of an item is represented by the following classes in the
+ * subpackage <code>state</code>:
+ * <ul>
+ * <li>{@link org.apache.jackrabbit.core.state.ItemState ItemState}</li>
+ * <li>{@link org.apache.jackrabbit.core.state.PropertyState PropertyState}</li>
+ * <li>{@link org.apache.jackrabbit.core.state.NodeState NodeState}</li>
+ * </ul>
+ * <p>
+ * There's one <code>SharedItemStateManager</code> for every workspace.
+ * It provides item state caching and it guarantees that there's only one
+ * (persistent) item state instance for any distinct item id in that workspace.
+ * <p>
+ * Every session has its own <code>SessionItemStateManager</code> that consists
+ * of the session's <code>TransientItemStateManager</code> and the workspace's
+ * <code>SharedItemStateManager</code>.
+ * <p>
+ * Each item (i.e. <code>NodeImpl</code> and <code>PropertyImpl</code>) instance
+ * is holding an <code>ItemState</code> instance. When e.g. a session is modifying
+ * a property by changing the property's value, a new transient item state
+ * is created by the session's <code>TransientItemStateManager</code>. This
+ * transient state is actually wrapping the (old) shared state (<i>copy on write</i>).
+ * The <code>PropertyImpl</code>'s state is then replaced by the new transient state.
+ * <p>
+ * Transient (i.e. unsaved) modifications are 'session-local',  i.e. they are not
+ * visible to other sessions. When the modifications are saved they become instantly
+ * visible to all sessions accessing the same workspace.
+ */
+package org.apache.jackrabbit.core;

jackrabbit-core/src/main/java/org/apache/jackrabbit/core/persistence/db/package-info.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ *
+ * This package contains the class <code>{@link SimpleDbPersistenceManager}</code>,
+ * a simple generic JDBC-based <code>PersistenceManager</code> for Jackrabbit.
+ * <p>
+ * It also contains [schemaName].ddl files which are read by
+ * <code>{@link SimpleDbPersistenceManager}</code>  in order to automatically
+ * create the required schema objects on the target database. Every line in a
+ * [schemaName].ddl file is executed separatly by calling
+ * <code>java.sql.Statement.execute(String)</code> where every occurence of the
+ * the string <code>"${schemaObjectPrefix}"</code> has been replaced with the
+ * value of the property <code>schemaObjectPrefix</code> (see
+ * <code>{@link SimpleDbPersistenceManager#setSchemaObjectPrefix(String)}</code>).
+ * The schema name is either set programmtically by calling
+ * <code>{@link SimpleDbPersistenceManager#setSchema(String)}</code> or configured
+ * through the <code>schema</code> bean property.
+ */
+package org.apache.jackrabbit.core.persistence.db;

jackrabbit-core/src/main/java/org/apache/jackrabbit/core/version/package-info.java

@@ -0,0 +1,41 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ *
+ * The versioning framework in jackrabbit consists of 3 layers. A persistence layer,
+ * an application layer and an presentation layer.<p>
+ * The persistence layer uses a 'normal' workspace as storage. The storage can later
+ * be exchanged by a more scaleable one. The application layer operates on the
+ * persistent one and provides the internal view of the version storage. It is
+ * manifested through the <code>InternalVersion</code> and
+ * <code>InternalVersionHistory</code> objects.
+ * The internal versions are also mapped to the content and exposed through the
+ * API (i.e. the <code>Version</code> extends <code>Node</code> and can be inspected
+ * with normal Node methods). Furthermore the version store is also exposed below
+ * <code>/jcr:system/jcr:versionStorage</code>. The exact structure of it is not
+ * defined yet, so applications should not relay on it and rather use
+ * <code>Node.getVersionHistory()</code> to access a particular version history or
+ * use the search mechanisms to find the respective versions.<p>
+ * The presentation layer is managed by the <code>VersionManager</code>. it is
+ * responsible for mapping the version storage to the content.
+ * <p>
+ * Open issues:
+ * <ul>
+ * <li>consider multi-threading behaviour
+ * </ul>
+ */
+package org.apache.jackrabbit.core.version;