Index: docs/reference/src/main/docbook/en-US/content/connectors/file_system.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/connectors/file_system.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/connectors/file_system.xml (working copy) @@ -137,11 +137,6 @@ following a communication failure. The default value is '0'. - rootNodeUuid - Optional property that, if used, specifies the UUID that should be used for the root node of each workspace. If no value is - specified, a default UUID is used. - - updatesAllowed Determines whether the content in the file system can be updated ("true"), or if the content may only be read ("false"). The default value is "false" to avoid unintentional security vulnerabilities. @@ -177,7 +172,6 @@ config.repositorySource("FS Store") .setProperty("workspaceRootPath", "/home/content/someApp") .setProperty("defaultWorkspaceName", "prod") .setProperty("predefinedWorkspaceNames", new String[] { "staging", "dev"}) - .setProperty("rootNodeUuid", UUID.fromString("fd129c12-81a8-42ed-aa4b-820dba49e6f0") .setProperty("updatesAllowed", "true") .setProperty("creatingWorkspaceAllowed", "false"); ]]> @@ -206,10 +200,10 @@ config.repositorySource("FS Store") mode:description="The repository for our content" mode:workspaceRootPath="/home/content/someApp" mode:defaultWorkspaceName="prod" - mode:predefinedWorkspaceNames="staging, dev" - mode:rootNodeUuid="fd129c12-81a8-42ed-aa4b-820dba49e6f0" mode:creatingWorkspacesAllowed="false" mode:updatesAllowed="true" > + staging + dev Index: docs/reference/src/main/docbook/en-US/content/connectors/infinispan.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/connectors/infinispan.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/connectors/infinispan.xml (working copy) @@ -97,7 +97,8 @@ rootNodeUuid Optional property that, if used, specifies the UUID that should be used for the root node of each workspace. If no value is - specified, a random UUID is generated each time that the repository is started. + specified, a pre-defined UUID constant is used. A custom value need only be supplied for Infinispan sources created prior to ModeShape 2.0, + or if a specific UUID is desired or needed. updatesAllowed @@ -117,7 +118,6 @@ config.repositorySource("Infinispan Store") .usingClass(InfinispanSource.class) .setDescription("The repository for our content") .setProperty("defaultWorkspaceName", "prod") - .setProperty("rootNodeUuid", UUID.fromString("84b73fc8-81a8-42ed-aa4b-3905094966f0") .setProperty("predefinedWorkspaceNames", new String[] { "staging", "dev"}); ]]> @@ -143,9 +143,10 @@ config.repositorySource("Infinispan Store") + mode:defaultworkspaceName="prod"> + staging + dev + Index: docs/reference/src/main/docbook/en-US/content/connectors/jboss_cache.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/connectors/jboss_cache.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/connectors/jboss_cache.xml (working copy) @@ -151,8 +151,10 @@ config.repositorySource("Store") mode:classname="org.modeshape.graph.connector.jbosscache.JBossCacheSource" mode:description="The repository for our content" mode:defaultworkspaceName="prod" - mode:rootNodeUuid="12083e7e-2b55-4c8d-954d-627a9f5c45c2" - mode:predefinedWorkspaceNames="staging,dev"/> + mode:rootNodeUuid="12083e7e-2b55-4c8d-954d-627a9f5c45c2"> + staging + dev + Index: docs/reference/src/main/docbook/en-US/content/connectors/subversion.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/connectors/subversion.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/connectors/subversion.xml (working copy) @@ -119,7 +119,7 @@ config.repositorySource("SVN Store") .setDescription("The ModeShape SVN repository (anonymous access)") .setProperty("repositoryRootUrl", "http://anonsvn.jboss.org/repos/modeshape"); .setProperty("defaultWorkspaceName", "trunk"); - .setProperty("predefinedWorkspaceNames", new String[] {"trunk" }); + .setProperty("predefinedWorkspaceNames", new String[] {"trunk","tags" }); ]]> Another way to configure the Subversion connector is to create &JcrConfiguration; instance and load an XML configuration file that contains a repository source that @@ -146,8 +146,9 @@ config.repositorySource("SVN Store") mode:description="The ModeShape SVN repository (anonymous access)" mode:repositoryRootUrl="http://anonsvn.jboss.org/repos/modeshape" mode:defaultWorkspaceName="trunk" - mode:predefinedWorkspaceNames="trunk" mode:defaultWorkspaceName="default" > + tags + trunk javax.jcr jcr - 1.0.1 + 2.0 test ]]> @@ -401,62 +407,76 @@ public interface &SequencerOutput; { public class &ImageMetadataSequencer; implements &StreamSequencer; { - public static final String METADATA_NODE = "image:metadata"; - public static final String IMAGE_PRIMARY_TYPE = "jcr:primaryType"; - public static final String IMAGE_MIXINS = "jcr:mixinTypes"; - public static final String IMAGE_MIME_TYPE = "jcr:mimeType"; - public static final String IMAGE_ENCODING = "jcr:encoding"; - public static final String IMAGE_FORMAT_NAME = "image:formatName"; - public static final String IMAGE_WIDTH = "image:width"; - public static final String IMAGE_HEIGHT = "image:height"; - public static final String IMAGE_BITS_PER_PIXEL = "image:bitsPerPixel"; - public static final String IMAGE_PROGRESSIVE = "image:progressive"; - public static final String IMAGE_NUMBER_OF_IMAGES = "image:numberOfImages"; - public static final String IMAGE_PHYSICAL_WIDTH_DPI = "image:physicalWidthDpi"; - public static final String IMAGE_PHYSICAL_HEIGHT_DPI = "image:physicalHeightDpi"; - public static final String IMAGE_PHYSICAL_WIDTH_INCHES = "image:physicalWidthInches"; - public static final String IMAGE_PHYSICAL_HEIGHT_INCHES = "image:physicalHeightInches"; + /** + * {@inheritDoc} + * + * @see StreamSequencer#sequence(InputStream, SequencerOutput, StreamSequencerContext) + */ + public void sequence( InputStream stream, + SequencerOutput output, + StreamSequencerContext context ) { - /** - * {@inheritDoc} - */ - public void sequence( &InputStream; stream, &SequencerOutput; output, - &SequencerContext; context ) { - &ImageMetadata; metadata = new &ImageMetadata;(); - metadata.setInput(stream); - metadata.setDetermineImageNumber(true); - metadata.setCollectComments(true); + ImageMetadata metadata = new ImageMetadata(); + metadata.setInput(stream); + metadata.setDetermineImageNumber(true); + metadata.setCollectComments(true); + + // Process the image stream and extract the metadata ... + if (!metadata.check()) { + metadata = null; + } - // Process the image stream and extract the metadata ... - if (!metadata.check()) { - metadata = null; - } - // Generate the output graph if we found useful metadata ... - if (metadata != null) { - // Place the image metadata into the output map ... - output.setProperty(METADATA_NODE, IMAGE_PRIMARY_TYPE, "image:metadata"); - // output.psetProperty(METADATA_NODE, IMAGE_MIXINS, ""); - output.setProperty(METADATA_NODE, IMAGE_MIME_TYPE, metadata.getMimeType()); - // output.setProperty(METADATA_NODE, IMAGE_ENCODING, ""); - output.setProperty(METADATA_NODE, IMAGE_FORMAT_NAME, metadata.getFormatName()); - output.setProperty(METADATA_NODE, IMAGE_WIDTH, metadata.getWidth()); - output.setProperty(METADATA_NODE, IMAGE_HEIGHT, metadata.getHeight()); - output.setProperty(METADATA_NODE, IMAGE_BITS_PER_PIXEL, metadata.getBitsPerPixel()); - output.setProperty(METADATA_NODE, IMAGE_PROGRESSIVE, metadata.isProgressive()); - output.setProperty(METADATA_NODE, IMAGE_NUMBER_OF_IMAGES, - metadata.getNumberOfImages()); - output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_WIDTH_DPI, - metadata.getPhysicalWidthDpi()); - output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_HEIGHT_DPI, - metadata.getPhysicalHeightDpi()); - output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_WIDTH_INCHES, - metadata.getPhysicalWidthInch()); - output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_HEIGHT_INCHES, - metadata.getPhysicalHeightInch()); - } - } + // Generate the output graph if we found useful metadata ... + if (metadata != null) { + PathFactory pathFactory = context.getValueFactories().getPathFactory(); + Path metadataNode = pathFactory.createRelativePath(ImageMetadataLexicon.METADATA_NODE); + + // Place the image metadata into the output map ... + output.setProperty(metadataNode, JcrLexicon.PRIMARY_TYPE, "image:metadata"); + // output.psetProperty(metadataNode, nameFactory.create(IMAGE_MIXINS), ""); + output.setProperty(metadataNode, JcrLexicon.MIMETYPE, metadata.getMimeType()); + // output.setProperty(metadataNode, nameFactory.create(IMAGE_ENCODING), ""); + output.setProperty(metadataNode, ImageMetadataLexicon.FORMAT_NAME, metadata.getFormatName()); + output.setProperty(metadataNode, ImageMetadataLexicon.WIDTH, metadata.getWidth()); + output.setProperty(metadataNode, ImageMetadataLexicon.HEIGHT, metadata.getHeight()); + output.setProperty(metadataNode, ImageMetadataLexicon.BITS_PER_PIXEL, metadata.getBitsPerPixel()); + output.setProperty(metadataNode, ImageMetadataLexicon.PROGRESSIVE, metadata.isProgressive()); + output.setProperty(metadataNode, ImageMetadataLexicon.NUMBER_OF_IMAGES, metadata.getNumberOfImages()); + output.setProperty(metadataNode, ImageMetadataLexicon.PHYSICAL_WIDTH_DPI, metadata.getPhysicalWidthDpi()); + output.setProperty(metadataNode, ImageMetadataLexicon.PHYSICAL_HEIGHT_DPI, metadata.getPhysicalHeightDpi()); + output.setProperty(metadataNode, ImageMetadataLexicon.PHYSICAL_WIDTH_INCHES, metadata.getPhysicalWidthInch()); + output.setProperty(metadataNode, ImageMetadataLexicon.PHYSICAL_HEIGHT_INCHES, metadata.getPhysicalHeightInch()); + } + } } + where the &ImageMetadataLexicon; class contains the &Name; constants and is defined as: + + /** + * A lexicon of names used within the image sequencer. + */ + @Immutable + public class &ImageMetadataLexicon; { + + public static class Namespace { + public static final String URI = "http://www.modeshape.org/images/1.0"; + public static final String PREFIX = "image"; + } + + public static final Name METADATA_NODE = new BasicName(Namespace.URI, "metadata"); + public static final Name FORMAT_NAME = new BasicName(Namespace.URI, "formatName"); + public static final Name WIDTH = new BasicName(Namespace.URI, "width"); + public static final Name HEIGHT = new BasicName(Namespace.URI, "height"); + public static final Name BITS_PER_PIXEL = new BasicName(Namespace.URI, "bitsPerPixel"); + public static final Name PROGRESSIVE = new BasicName(Namespace.URI, "progressive"); + public static final Name NUMBER_OF_IMAGES = new BasicName(Namespace.URI, "numberOfImages"); + public static final Name PHYSICAL_WIDTH_DPI = new BasicName(Namespace.URI, "physicalWidthDpi"); + public static final Name PHYSICAL_HEIGHT_DPI = new BasicName(Namespace.URI, "physicalHeightDpi"); + public static final Name PHYSICAL_WIDTH_INCHES = new BasicName(Namespace.URI, "physicalWidthInches"); + public static final Name PHYSICAL_HEIGHT_INCHES = new BasicName(Namespace.URI, "physicalHeightInches"); + + } + Notice how the image metadata is extracted and the output graph is generated. A single node is created with the name image:metadata Index: docs/reference/src/main/docbook/en-US/content/developers/testing.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/developers/testing.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/developers/testing.xml (working copy) @@ -134,13 +134,34 @@ Many Java specifications provide TCK test suites that can be used to check or verify that an implementation correctly implements the API or SPI defined by the specification. These TCK tests vary by technology, but - JSR-170 does provide TCK tests that ensure that a JCR repository implementation + JSR-283 does provide TCK tests that ensure that a JCR repository implementation exhibits the correct and expected behavior. - - ModeShape has implemented all of the JCR Level 1 and Level 2 features, along with the optional locking, query, versioning, and observation - features. Though the JCR-SQL optional feature has already been deprecated in JSR-283 and is superseded - by JCR-SQL2, both are SQL-like query languages are supported in ModeShape. + ModeShape now implements all of the required JCR 2.0 features: + + repository acquisition + authentication + reading/navigating + query + export + node type discovery + permissions and capability checking + + and implements most of the optional JCR 2.0 features: + + writing + import + observation + workspace management + versioning + locking + node type management + same-name siblings + orderable child nodes + + ModeShape supports the JCR-SQL2 and JQOM query languages defined in JSR-283, + plus the XPath and JCR-SQL languages defined in JSR-170 but deprecated in + JSR-283. The ModeShape project also frequently runs the JCR TCK unit tests from the reference implementation. (These tests are not @@ -148,13 +169,12 @@ module against the in-memory repository to ensure our JCR implementation behaves correctly, and the same tests are run in the modeshape-integration-tests module against a variety of connectors to ensure they're implemented correctly. The modeshape-jcr-tck module runs all of these - TCK unit tests, and currently there are only a handful of failures due to known issues (see MODE-563 - and MODE-760). + TCK unit tests, and currently there are only a handful of failures due to known issues (see the + JCR specification support section for details). - The &versionNumber; release passes all of the JCR Level 1, Level2, versioning, and locking TCK tests (and almost all of them for observation - and query), but still needs to be certified before being considered fully compliant with JCR 1.0. - The ModeShape project plans to focus on attaining this certification in the very near future. + The ModeShape project has not yet been certified to be fully-compliant with the JCR 2.0 specification, but does plan + on attaining this certification in the very near future. Index: docs/reference/src/main/docbook/en-US/content/developers/tools.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/developers/tools.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/developers/tools.xml (working copy) @@ -102,7 +102,7 @@ Currently, ModeShape is developed and built using JDK 6. So if you're trying to get ModeShape to compile locally, you should make sure you have the JDK 6 installed and are using it. - If you're a contributor, you should make sure that you're using JDK 6 before committing any changes. + If you're a contributor, you should make sure that you're using JDK 6 before committing any changes. When installing a JDK, simply follow the procedure for your particular platform. On most platforms, this should set the @@ -221,78 +221,44 @@ ModeShape uses Maven 2 for its build system, as is this example. Using Maven 2 has several advantages, including the ability to manage dependencies. If a library is needed, Maven automatically finds and downloads that library, plus everything that library needs. This means that it's very easy to build the examples - or even create a maven project that - depends on the ModeShape JARs. + depends on the ModeShape JARs. + - To use Maven with ModeShape, you'll need to have JDK 6 and Maven 2.0.9 (or higher). + To use Maven with ModeShape, you'll need to have JDK 6 and Maven 2.0.9 (or higher). + Maven can be downloaded from http://maven.apache.org/, and is installed by unzipping the maven-2.0.9-bin.zip or maven-2.0.11-bin.zip file to a convenient location on your local disk. - Simply add $MAVEN_HOME/bin to your path and add the following profile to your ~/.m2/settings.xml file: - - - - - jboss.repository - - - !jboss.repository.off - - - - - snapshots.jboss.org - http://snapshots.jboss.org/maven2 - - true - - - - repository.jboss.org - http://repository.jboss.org/maven2 - - false - - - - - - repository.jboss.org - http://repository.jboss.org/maven2 - - false - - - - snapshots.jboss.org - http://snapshots.jboss.org/maven2 - - true - - - - - - -]]> - This profile informs Maven of the two JBoss repositories (snapshots - and releases) that contain all of the JARs for ModeShape and all dependent libraries. - + Then add $MAVEN_HOME/bin to your path. + While you're adding $MAVEN_HOME/bin to your path, you should also set the $MAVEN_OPTS environment variable - to "-Xmx384m". If you don't do this, you'll likely see an java.lang.OutOfMemoryError sometime during a full + to "-Xmx384m". If you don't do this, you will likely see an java.lang.OutOfMemoryError sometime during a full build. + + The JBoss Maven repository provides a central location for not only the artifacts produced by the JBoss.org projects (well, at least those + that use Maven), but also is where those projects can place the artifacts that they depend on. The new + JBoss.org Maven repository uses the + Nexus repository manager, and is configured to proxy other Maven repositories + and automatically cache the third-party artifacts used in our builds. This helps ensure that developers have easy + access to these artifacts (including sources) and that the project (and dependencies) can always be rebuilt when needed. + + + For more information about the JBoss Maven repository, see the + announcement + and documentation. + - The JBoss Maven repository provides a central location for not only the artifacts produced by the JBoss.org projects (well, at least those - that use Maven), but also is where those projects can place the artifacts that they depend on. ModeShape has a policy that - the source code and JARs for all dependencies must be loaded into the - JBoss Maven repository. It may be a little bit more work for the developers, but it does help ensure that developers have easy - access to the source and that the project (and dependencies) can always be rebuilt when needed. + Previous versions of ModeShape made use of the older JBoss.org Maven repository, and required modifying your local + ~/.m2/settings.xml file. This is no longer required by users or contributors, since the ModeShape POM + file is set up to reference the new JBoss.org repository. - For more information about the JBoss Maven repository, including instructions for adding source and JAR artifacts, - see the JBoss.org Wiki. + However, if you are one of the ModeShape contributors that will be making and publishing ModeShape releases into the + JBoss.org repository, you will need to modify your ~/.m2/settings.xml file to contain your + JBoss.org repository credentials. For details, see the + documentation for developers. @@ -328,6 +294,15 @@ + mvn clean install -P integration + This "integration build" does everything the "quick" build does plus compiling and + running the integration tests, documentation, and examples, all of which add several minutes over the "quick build". + Since the integration tests include running the JCR TCK tests against a variety of configurations with different + connectors, this build should be run before committing changes to the JCR implementation code. + Also, HSQLDB is used when a database is needed. + + + mvn clean install -Ddatabase=dbprofile Same as the "quick build", except that it specifies the database management system that is to be used by the tests. @@ -346,23 +321,18 @@ - mvn -P integration clean install - This "integration build" does everything the "quick" build does plus it compiles and - runs the integration tests, which take several extra minutes to run. - Also, HSQLDB is used when a database is needed. - - - - mvn -P integration clean install -Ddatabase=dbprofile + mvn clean install -Ddatabase=dbprofile -P integration This does the same as the "integration build", except that it specifies the database management system that is to be used by the unit and integration tests. Options for the "dbprofile" values are the same as listed above. - mvn -P assembly clean install - This runs a builds all source code, documentation, JavaDoc, runs all unit and integration tests, - and produces all assemblies (e.g., zip files). + mvn clean install -P assembly + Clean up all produced artifacts; compile the source code and test cases; + run all of the unit tests; install the resulting JAR artifact(s); compile and run all integration tests; + build the documentation; produce the JavaDoc; and build the ZIP assemblies for the source, binary distribution, + documentation, JavaDoc, and examples. HSQLDB is used when a database is needed. @@ -390,14 +360,20 @@ - Continuous + Continuous Continuous build that runs an integration build after changes are committed to SVN. SVN is polled every 15 minutes. - Nightly + Nightly Integration build that runs every night (usually around 2 a.m. EDT), regardless of whether changes have been committed to SVN since the previous night. + + JCR 2.0 API Compatibility + Continuous build that runs every night (usually around 2 a.m. EDT), regardless of whether changes have been committed to SVN + since the previous night. This job runs a full integration build with all of the JCR TCK unit tests, and may have + several failures. + @@ -407,7 +383,7 @@ Many of the ModeShape committers use the Eclipse IDE, and all project files required by Eclipse are committed in SVN, making it pretty easy to get an Eclipse workspace running with all of the ModeShape projects. - We're using the latest released version of Eclipse, + We're using either the Ganymede or Helios (latest) versions of Eclipse, available from Eclipse.org. Simply follow the instructions for your platform. @@ -419,7 +395,7 @@ formatting preferences for the ModeShape project. - Then install Eclipse plugins for SVN and Maven. (Remember, you will have to restart Eclipse after installing them.) + Then install Eclipse plugins for SVN, Maven, and optionally Git. (Remember, you will have to restart Eclipse after installing them.) We use the following plugins: @@ -430,20 +406,24 @@ Eclipse Plugins - Update Site URLs + Installation documentation Subversive SVN Client - http://www.polarion.org/projects/subversive/download/eclipse/2.0/update-site/ - http://www.polarion.org/projects/subversive/download/integrations/update-site/ + http://www.polarion.com/products/svn/subversive/download.php Maven Integration for Eclipse - http://m2eclipse.sonatype.org/update/ + http://m2eclipse.sonatype.org/installing-m2eclipse.html + + + + Git Integration for Eclipse + http://www.eclipse.org/egit/download/ @@ -567,8 +547,8 @@ The release has been performed, but we still need to build and deploy the real artifacts - to the JBoss Maven repository. To do - this, go to a working area and check out the recently-produced SVN tag (using the correct {release-number}): + to the JBoss Maven repository. + To do this, go to a working area and check out the recently-produced SVN tag (using the correct {release-number}): $ svn checkout https://anonsvn.jboss.org/repos/modeshape/tags/modeshape-{release-number}/ @@ -577,22 +557,15 @@ $ mvn clean deploy This will rebuild all the artifacts (from your local copy of the tagged source) and deploy them - to the local file system, which is comprised of a local checkout of the JBoss Maven2 repository - in a location specified by a combination of the <distributionManagement> section of several pom.xml - files and your personal settings.xml file. Once this Maven command completes, you will need to - commit the new files after they are deployed. For more information, see the - JBoss wiki. - - - At this point, the software has been released and tagged, and it's been deployed to a local checked-out copy of the - ModeShape Maven 2 repository (via the "<distribution>" section of the pom.xml files). Those need to be committed - into the Maven 2 repository using SVN. And finally, the last thing is to publish the release onto - the project's downloads and documentation pages. + to the JBoss.org Maven repository in staging area. Then, using the JBoss.org web interface, close the staging area + and (after validating the artifacts uploaded to the staging area) promote them into the releases repository + (see the repository documentation for details). - The assemblies of the source, binaries, etc. also need to be published onto the &Downloads; area of the - the project page. This process is expected to change, as JBoss.org - improves its infrastructure. + At this point, the software has been tagged, released, and deployed to the JBoss.org Maven repository. The last + tasks are to update the ModeShape.org website (using Magnolia) and publish the release onto + the project's downloads and documentation pages + using sftp and rsync (Red Hat employees only). Index: docs/reference/src/main/docbook/en-US/content/future.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/future.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/future.xml (working copy) @@ -32,13 +32,39 @@ Looking to the future ModeShape &versionNumber; provides a very capable JCR implementation with powerful and unique features not matched - by other implementations. This release adds several key features, such as JCR versioning and a JCR connector, + by other implementations. This release moves ModeShape to the JCR 2.0 API, implements several new features, and includes fixes and improvements. + ModeShape now implements all of the required JCR 2.0 features: + + repository acquisition + authentication + reading/navigating + query + export + node type discovery + permissions and capability checking + + and implements most of the optional JCR 2.0 features: + + writing + import + observation + workspace management + versioning + locking + node type management + same-name siblings + orderable child nodes + + ModeShape supports the JCR-SQL2 and JQOM query languages defined in JSR-283, + plus the XPath and JCR-SQL languages defined in JSR-170 but deprecated in + JSR-283. + - At this point, ModeShape passes all of the JCR Technology Compatibility Kit (TCK) tests - for Level 1, Level 2, and the optional locking and versioning features (plus almost all of the tests for the - optional observation feature). We'll soon begin the process of attaining JCR certification for ModeShape. + At this point, ModeShape passes virtually all of the JCR Technology Compatibility Kit (TCK) tests, + except for a few known issues with ModeShape as well as bugs in the TCK tests. As soon as these + are fixed, we'll start the process of attaining JCR 2.0 certification for ModeShape. What's next for ModeShape? Index: docs/reference/src/main/docbook/en-US/content/introduction.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/introduction.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/introduction.xml (working copy) @@ -31,12 +31,12 @@ Introduction to ModeShape - ModeShape is a JCR implementation that provides access to content stored in many different kinds of systems. + ModeShape is a JCR implementation that provides access to content stored in many different kinds of systems. A ModeShape repository isn't yet another silo of isolated information, but rather it's a JCR view of the information you already have in your environment: files systems, databases, other repositories, services, applications, etc. - To your applications, ModeShape looks and behaves like a regular JCR repository. Using the standard JCR API, + To your applications, ModeShape looks and behaves like a regular JCR repository. Using the standard JCR 2.0 API (a.k.a. JSR-283), applications can search, navigate, version, and listen for changes in the content. But under the covers, ModeShape gets its content by federating multiple back-end systems (like databases, services, other repositories, etc.), allowing those systems to continue "owning" the information while ensuring the unified repository stays up-to-date @@ -182,18 +182,21 @@ transactions, and observation. Because of this, content repositories are used by content management systems (CMS), document management systems (DMS), and other applications that manage electronic files (e.g., documents, images, multi-media, web content, etc.) and metadata associated with them (e.g., author, date, status, security information, etc.). The - Content Repository for Java technology API - provides a standard Java API for working with content repositories. Abbreviated "JCR", this API was developed as part of the - Java Community Process under JSR-170 - and has been revised under JSR-283. + Content Repository for Java technology API + provides a standard Java API for working with content repositories. Abbreviated "JCR", this API was developed through the + Java Community Process originally under JSR-170 (as "JCR 1.0"), but has + since been revised and improved as "JCR 2.0" under JSR-283. - The JCR API provides a number of information services that are needed by many applications, + The JCR 2.0 API provides a number of information services that are needed by many applications, including: read and write access to information; the ability to structure information in a hierarchical and flexible manner that can adapt - and evolve over time; ability to work with unstructured content; ability to (transparently) handle large strings; + and evolve over time; ability to work with structured, semi-structured, and unstructured content; ability to (transparently) handle large strings; notifications of changes in the information; search and query; versioning of information; access control; integrity constraints; participation within distributed transactions; explicit locking of content; and of course persistence. + + ModeShape implements the JCR 2.0 API, including many of the optional features. +
JCR API features @@ -202,18 +205,18 @@ Project roadmap - The roadmap for ModeShape is managed in the project's + The ModeShape open source project uses its JIRA instance - . The roadmap shows the different tasks, requirements, issues and other activities that have been targeted to each of the - upcoming releases. (The - roadmap report - always shows the next three releases.) + to track issues for tasks, requirements, bugs, and other activities. The + roadmap report + shows how each of these issues are targeted to the upcoming releases, while the change log report + shows all of the issues that were fixed in each of the past releases. By convention, the ModeShape project team periodically review JIRA issues that aren't targeted to a release, and then schedule them based upon current workload, severity, and the roadmap. And if we review an issue and don't know how to target it, we target it to the - Future Releases + Future Releases bucket. @@ -224,30 +227,39 @@ ModeShape modules - ModeShape consists of the following modules: + ModeShape consists quite a few separate modules. Just a few of these make up the essential core components of the system: modeshape-jcr - contains ModeShape's implementation of the JCR API. If you're using ModeShape as a JCR repository, this is the + contains ModeShape's implementation of the JCR 2.0 API. If you're using ModeShape as a JCR repository, this is the top-level dependency that you'll want to use. The module defines all required dependencies, except for the repository connector(s) and any sequencer implementations needed by your configuration. - As we'll see later on, using ModeShape as a JCR repository is easy: simply create a configuration, - start ModeShape's JCR engine, get the JCR &Repository; object for your repository, and then use the JCR API. + As we'll see later on, using ModeShape as a JCR repository is as easy as defining a configuration, + obtaining the JCR &Repository; object for your repository using the &RepositoryFactory;, and then using the standard JCR API. This module also uses the JCR unit tests from the reference implementation to verify the behavior of the ModeShape implementation. modeshape-jcr-api - defines a number of interfaces that extend a few of the JCR API interfaces, adding some of the methods that appear - in JCR 2.0. This module serves as a temporary bridge to some very useful JCR 2.0 functionality. - Plus, this module defines a Repositories interface that defines a way to look up javax.jcr.Repository + defines a number of interfaces that add a few interfaces or extend several of the JCR API interfaces. + For example, this module defines a &Repositories; interface that defines a way to look up javax.jcr.Repository + instances by name, and that is implemented by the ModeShape JcrEngine. It also defines several new + interfaces that extend the JCR 2.0 API's Query Object Model with additional behavior, including more criteria options + (such as &Between;, &NodeDepth;, &NodePath;, &ReferenceValue;), a formal &Limit; clause, and a &SetQuery; for unions, intersects, + and difference queries. + This module is very small and is only dependent upon the JCR API, and ModeShape is designed so that client applications can depend + only upon this module without having to depend on the modeshape-jcr interfaces or its dependencies. + For example, this module defines a &Repositories; interface that defines a way to look up javax.jcr.Repository instances by name, and that is implemented by the ModeShape JcrEngine, allowing client applications to dependency on this module to look up repositories by name without having to depend on the - modeshape-jcr interfaces or its dependencies. + + Several other modules are also essential, but for the most part are hidden to client applications as they provide components used + within the JCR implementation: + modeshape-repository @@ -278,20 +290,9 @@ - There are several modules that provide system- and integration-level tests: - - - - modeshape-integration-tests - provides a home for all of the integration tests that involve more components that just unit tests. Integration - tests are often more complicated, take longer, and involve testing the integration and functionality of multiple - components (whereas unit tests focus on testing a single class or component and may use stubs or mock objects - to isolate the code being tested from other related components). - - - - The following modules are optional extensions that may be used selectively and as needed - (and are located in the source under the extensions/ directory): + Most of the ModeShape modules, however, are optional extensions. Many of these depend on third party libraries, so you + will probably want to include only those modules that provide functionality you'll use in your repository. + These modules are located in the source under the extensions/ directory. @@ -338,7 +339,7 @@ modeshape-connector-jcr - is a ModeShape repository connector that accesses and stores content in an external JCR repository. This allows + is a ModeShape repository connector that accesses and stores content in an external JCR 2.0 repository. This allows ModeShape to integrate with other JCR implementations and even federate multiple JCR repositories into a single unified repository. Any differences in namespaces are automatically handled, although node types used by the content in the external JCR repository must also be registered into the ModeShape repository using the connector. @@ -467,7 +468,9 @@ The following modules make up the various web application projects (and are located in the source under the web/ - directory): + directory). You may be able to use these artifacts "out of the box", but more likely the configuration defined in the WAR files + will not be exactly what you want for your environment. In this case, you can replicate one of our "-war" modules and customize + the configuration settings to easily assembly a custom WAR. @@ -517,7 +520,7 @@ - There are also documentation modules (located in the source under the + There are also modules for ModeShape's documentation (located in the source under the docs/ directory): @@ -544,7 +547,8 @@ - Another module provides some utility functionality: + Another module provides a utility to generate DDL for a variety of database management systems. This module is likely + not used in client applications, but rather used during development to generate the desired DDL. @@ -554,7 +558,8 @@ - There is another module that runs the full suite of JCR TCK tests, and which at the moment still contains some failures. + There is another module that runs the full suite of JCR TCK tests, and which at the moment still contains a few failures. + This module is never needed in client applications. @@ -565,6 +570,18 @@ + Another module provides system- and integration-level tests is never needed in client applications: + + + + modeshape-integration-tests + provides a home for all of the integration tests that involve more components that just unit tests. Integration + tests are often more complicated, take longer, and involve testing the integration and functionality of multiple + components (whereas unit tests focus on testing a single class or component and may use stubs or mock objects + to isolate the code being tested from other related components). + + + Finally, there is a Maven parent pom.xml file that aggregates all of the other projects, provides common defaults for Maven plugins and dependency versions used throughout the modules, and definition of various asset files to help build the necessary Maven artifacts during a build. @@ -572,26 +589,44 @@ Each of these modules is a Maven project with a group ID of org.modeshape - . All of these projects correspond to artifacts in the - JBoss Maven 2 Repository - . + . All of these projects correspond to artifacts in the + JBoss Maven 2 Repository, the settings for which are described on the + JBoss.org wiki. What's new? - With version &versionNumber;, ModeShape adds support for the JCR-SQL query language, - improvements to the existing connectors, and quite a few bug fixes and improvements. - - This means that ModeShape now implements all of the JCR Level 1 and Level 2 features, - along with the optional locking, query, versioning, and observation features. - Of all of the JCR TCK tests, the only failures are related to several known issues: two from observation (see MODE-563) - one from query tests (see MODE-760), and two from invalid/incorrect queries created by the tests. + With version &versionNumber;, ModeShape introduces support for the JCR 2.0 API, + improvements to existing connectors, and quite a few bug fixes and improvements. - + This means that ModeShape now implements all of the required JCR 2.0 features: + repository acquisition, authentication, reading/navigating, query, export, node type discovery, and permissions and + capability checking. + ModeShape also implements most of the optional JCR 2.0 features: + writing, import, observation, workspace management, versioning, locking, node type management, same-name siblings, + and orderable child nodes. + The remaining optional features (shareable nodes, access control management, lifecycle management, + retention and hold, and transactions) will be introduced in future versions. + + + + ModeShape &versionNumber; currently passes 1371 of the 1391 JCR TCK tests, where 17 of these 20 failures appear + to be bugs in the TCK tests (see + JCR-2648, + JCR-2661, + JCR-2662, and + JCR-2663). The remaining 3 failures are + due to known issues (see + MODE-759, + MODE-760, + MODE-786). + + + Index: docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml (working copy) @@ -29,487 +29,305 @@ %CustomDTD; ]> - Configuring and Using ModeShape - Using ModeShape within your application is actually quite straightforward. As you'll see in this chapter, - the first step is setting up ModeShape and starting the JcrEngine. After that, you obtain the - javax.jcr.Repository instance for a named repository and just use the standard JCR API throughout your - application. Alternatively, you can use the ModeShape implementation of the &RepositoryFactory; interface to access - your repository. + Configuration + + Using ModeShape within your application is actually quite straightforward, and with JCR 2.0 it is possible for your + application to do everything using only the JCR 2.0 API. Your application will first obtain a javax.jcr.Repository instance, + and will use that object to create sessions through which your application will read, modify, search, + or monitor content in the repository. - - ModeShape's JcrEngine - - ModeShape encapsulates everything necessary to run one or more JCR repositories into a single &JcrEngine; instance. - This includes all underlying repository sources, the pools of connections to the sources, the sequencers, - the MIME type detector(s), and the &Repository; implementations. - - - Obtaining a &JcrEngine; instance is very easy - assuming that you have a valid &JcrConfiguration; instance. We'll see - how to get one of those in a little bit, but if you have one then all you have to do is build and start the engine: - - + + However, before you can use ModeShape, you need to configure it, and that's what this chapter covers. + + + Configuring ModeShape - Obtaining a JCR &Repository; instance is a matter of simply asking the engine for it by the name defined in the configuration: - - + There really are three options: + + + Load from a file is conceptually the most straightforward and requires the least amount + of Java code, but it does requires having a configuration file. This is easy, allows one to manage configurations in version control, + and will likely be the approach most applications use. + + + Programmatic configuration allows an application to define and edit + a configuration using Java code. This is useful when you cannot pre-define your configuration, or when you want to start + with a baseline configuration, make programmatic changes based upon some inputs or preferences, and then save + the configuration to a file. + + + Load from a configuration repository is an advanced technique + that allows multiple &JcrEngine; instances (usually in different processes perhaps on different machines) + to easily access a (shared) configuration. + + + + + Each of these approaches has their obvious advantages, so the choice of which one to use is entirely up to you. + + + Loading from a Configuration File - At this point, your application can proceed by working with the JCR API. + Loading the ModeShape configuration from a file is actually very simple: + - And, once you're finished with the &JcrEngine;, you should shut it down: + where the file parameter can actually be a &File; instance, a &URL; to the file, an &InputStream; + containing the contents of the file, or even a &String; containing the contents of the file. - + + The loadFrom(...) method can be called any number of times, but each time it is called it completely wipes + out any current notion of the configuration and replaces it with the configuration found in the file. + + - When the shutdown() method is called, the &Repository; instances managed by the engine are marked as being shut down, - and they will not be able to create new &Session;s. However, any existing &Session;s or ongoing operations (e.g., event notifications) - present at the time of the shutdown() call will be allowed to finish. - In essence, shutdown() is a graceful request, and since it may take some time to complete, - you can wait until the shutdown has completed by simply calling awaitTermination(...) as shown above. - This method will block until the engine has indeed shutdown or until the supplied time duration has passed (whichever comes first). - And, yes, you can call the awaitTermination(...) method repeatedly if needed. + There is an optional second parameter that defines the &Path; within the configuration file identifying the parent node of the various + configuration nodes. If not specified, it assumes "/". This makes it possible for the configuration content to be + located at a different location in the hierarchical structure. (This is not often required, but when it is required + this second parameter is very useful.) - - - JcrConfiguration - The previous section assumed the existence of a &JcrConfiguration;. It's not really that creating an instance is all that difficult. - In fact, there's only one no-argument constructor, so actually creating the instance is a piece of cake. What can be a little more challenging, - though, is setting up the &JcrConfiguration; instance, which must define the following components: - - - Repository sources are the POJO objects that each describe a particular - location where content is stored. Each repository source object is an instance of a ModeShape connector, and is configured - with the properties that particular source. ModeShape's &RepositorySource; classes are analogous to JDBC's &DataSource; classes - - they are implemented by specific connectors (aka, "drivers") for specific kinds of repository sources (aka, "databases"). - Similarly, a &RepositorySource; instance is analogous to a &DataSource; instance, with bean properties for each configurable - parameter. Therefore, each repository source definition must supply the name of the &RepositorySource; class, any - bean properties, and, optionally, the classpath that should be used to load the class. - - - Repositories define the JCR repositories that are available. Each - repository has a unique name that is used to obtain the &Repository; instance from the &JcrEngine;'s getRepository(String) - method, but each repository definition also can include the predefined namespaces (other than those automatically defined by - ModeShape), various options, and the node types that are to be available in the repository without explicit registration - through the JCR API. - - - Sequencers define the particular sequencers that are available for use. - Each sequencer definition provides the path expressions governing which nodes in the repository should be sequenced when those nodes change, - and where the resulting output generated by the sequencer should be placed. The definition also must state the name of - the sequencer class, any bean properties and, optionally, the classpath that should be used to load the class. - - - MIME type detectors define the particular MIME type detector(s) that should - be made available. A MIME type detector does exactly what the name implies: it attempts to determine the MIME type given a - "filename" and contents. ModeShape automatically uses a detector that uses the file extension to identify the MIME type, - but also provides an implementation that uses an external library to identify the MIME type based upon the contents. - The definition must state the name of the detector class, any bean properties and, optionally, the classpath that should - be used to load the class. - - + Here is the configuration file that is used in the repository example, though it has been simplified a bit and most comments + have been removed for clarity): + + + + + + + + + + + + + + + + + + + + + workspace2 + workspace3 + + + + + + + + + + +]]> + + + Programmatic Configuration - There really are three options: - - - Load from a file is conceptually the easiest and requires the least amount - of Java code, but it now requires a configuration file. - - - Load from a configuration repository is not much more complicated than loading - from a file, but it does allow multiple &JcrEngine; instances (usually in different processes perhaps on different machines) - to easily access their (shared) configuration. And technically, loading the configuration from a file really just creates an - &InMemoryRepositorySource;, imports the configuration file into that source, and then proceeds with this approach. - - - Programmatic configuration is always possible, even if the configuration is loaded - from a file or repository. Using the &JcrConfiguration;'s API, you can define (or update or remove) all of the definitions that make - up a configuration. - - + Defining the configuration programmatically is not terribly complicated, and it for obvious reasons results in more verbose Java code. + But this approach is very useful and often the easiest approach when the configuration must change or is a reflection of other + dynamic information. - Each of these approaches has their obvious advantages, so the choice of which one to use is entirely up to you. + The &JcrConfiguration; class was designed to have an easy-to-use API that makes it easy to configure each of the different kinds of + components, especially when using an IDE with code completion. Here are several examples: - - Loading from a Configuration File - - Loading the ModeShape configuration from a file is actually very simple: + + Repository Sources + Each repository source definition must include the name of the &RepositorySource; class as well as each bean property + that should be set on the object: - + - where the file parameter can actually be a &File; instance, a &URL; to the file, an &InputStream; - containing the contents of the file, or even a &String; containing the contents of the file. + This example defines an in-memory source with the name "source A", a description, and a single "defaultWorkspaceName" bean property. + Different &RepositorySource; implementations will the bean properties that are required and optional. + Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from + the classpath or from a specific classpath). - The loadFrom(...) method can be called any number of times, but each time it is called it completely wipes - out any current notion of the configuration and replaces it with the configuration found in the file. + Each time repositorySource(String) is called, it will either load the existing definition with the supplied + name or will create a new definition if one does not already exist. To remove a definition, simply call remove() + on the result of repositorySource(String). + The set of existing definitions can be accessed with the repositorySources() method. + + + Repositories + Each repository must be defined to use a named repository source, but all other aspects (e.g., namespaces, node types, options) + are optional. + - There is an optional second parameter that defines the &Path; within the configuration file identifying the parent node of the various - configuration nodes. If not specified, it assumes "/". This makes it possible for the configuration content to be - located at a different location in the hierarchical structure. (This is not often required, but when it is required - this second parameter is very useful.) - - - Here is the configuration file that is used in the repository example, though it has been simplified a bit and most comments - have been removed for clarity): - - - - - - - - - - - - - - - - - - - - - - - - workspace2 - - - - - - - - - - - ]]> - - - Loading from a Configuration Repository - - Loading the ModeShape configuration from an existing repository is also pretty straightforward. Simply create and configure the - &RepositorySource; instance to point to the desired repository, and then call the loadFrom(&RepositorySource; source) - method: - - - - This really is a more advanced way to define your configuration, so we won't go into how you configure a &RepositorySource;. + This example defines a repository that uses the "source 1" repository source (which could be a federated source, an in-memory source, + a database store, or any other source). Additionally, this example adds the node types in the "myCustomNodeTypes.cnd" file as those + that will be made available when the repository is accessed. It also defines the "http://www.example.com/acme" namespace, + and finally sets the "JAAS_LOGIN_CONFIG_NAME" option to define the name of the JAAS login configuration that should be used by + the ModeShape repository. - The loadFrom(...) method can be called any number of times, but each time it is called it completely wipes - out any current notion of the configuration and replaces it with the configuration found in the file. + Each time repository(String) is called, it will either load the existing definition with the supplied + name or will create a new definition if one does not already exist. To remove a definition, simply call remove() + on the result of repository(String). + The set of existing definitions can be accessed with the repositories() method. + + + Sequencers + Each defined sequencer must specify the name of the &StreamSequencer; implementation class as well as the path expressions + defining which nodes should be sequenced and the output paths defining where the sequencer output should be placed (often as a function + of the input path expression). + - There is an optional second parameter that defines the name of the workspace in the supplied source where the configuration content - can be found. It is not needed if the workspace is the source's default workspace. - There is an optional third parameter that defines the &Path; within the configuration repository identifying the parent node of the various - configuration nodes. If not specified, it assumes "/". This makes it possible for the configuration content to be - located at a different location in the hierarchical structure. (This is not often required, but when it is required - this second parameter is very useful.) - - - - Programmatic Configuration - - Defining the configuration programmatically is not terribly complicated, and it for obvious reasons results in more verbose Java code. - But this approach is very useful and often the easiest approach when the configuration must change or is a reflection of other - dynamic information. - - - The &JcrConfiguration; class was designed to have an easy-to-use API that makes it easy to configure each of the different kinds of - components, especially when using an IDE with code completion. Here are several examples: + This shows an example of a sequencer definition named "Image Sequencer" that uses the &ImageMetadataSequencer; class + (loaded from the classpath), that is to sequence the "jcr:data" property on any new or changed nodes that are named + "jcr:content" below a parent node with a name ending in ".jpg", ".jpeg", ".gif", ".bmp", ".pcx", ".iff", ".ras", + ".pbm", ".pgm", ".ppm" or ".psd". The output of the sequencing operation should be placed at the "/images/$1" node, + where the "$1" value is captured as the name of the parent node. (The capture groups work the same way as regular expressions.) + Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from + the classpath or from a specific classpath). - - Repository Sources - Each repository source definition must include the name of the &RepositorySource; class as well as each bean property - that should be set on the object: - - - - This example defines an in-memory source with the name "source A", a description, and a single "defaultWorkspaceName" bean property. - Different &RepositorySource; implementations will the bean properties that are required and optional. - Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from - the classpath or from a specific classpath). - - - Each time repositorySource(String) is called, it will either load the existing definition with the supplied - name or will create a new definition if one does not already exist. To remove a definition, simply call remove() - on the result of repositorySource(String). - The set of existing definitions can be accessed with the repositorySources() method. - - - - - Repositories - Each repository must be defined to use a named repository source, but all other aspects (e.g., namespaces, node types, options) - are optional. - - - This example defines a repository that uses the "source 1" repository source (which could be a federated source, an in-memory source, - a database store, or any other source). Additionally, this example adds the node types in the "myCustomNodeTypes.cnd" file as those - that will be made available when the repository is accessed. It also defines the "http://www.example.com/acme" namespace, - and finally sets the "JAAS_LOGIN_CONFIG_NAME" option to define the name of the JAAS login configuration that should be used by - the ModeShape repository. - - - Each time repository(String) is called, it will either load the existing definition with the supplied - name or will create a new definition if one does not already exist. To remove a definition, simply call remove() - on the result of repository(String). - The set of existing definitions can be accessed with the repositories() method. - - - - - Sequencers - Each defined sequencer must specify the name of the &StreamSequencer; implementation class as well as the path expressions - defining which nodes should be sequenced and the output paths defining where the sequencer output should be placed (often as a function - of the input path expression). - - - This shows an example of a sequencer definition named "Image Sequencer" that uses the &ImageMetadataSequencer; class - (loaded from the classpath), that is to sequence the "jcr:data" property on any new or changed nodes that are named - "jcr:content" below a parent node with a name ending in ".jpg", ".jpeg", ".gif", ".bmp", ".pcx", ".iff", ".ras", - ".pbm", ".pgm", ".ppm" or ".psd". The output of the sequencing operation should be placed at the "/images/$1" node, - where the "$1" value is captured as the name of the parent node. (The capture groups work the same way as regular expressions.) - Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from - the classpath or from a specific classpath). - - - Each time sequencer(String) is called, it will either load the existing definition with the supplied - name or will create a new definition if one does not already exist. To remove a definition, simply call remove() - on the result of sequencer(String). - The set of existing definitions can be accessed with the sequencers() method. - - - Note that in addition to including a description for the configuration, it is also possible to set sequencer-specific properties - using the setProperty(String,String[]) method. When ModeShape uses this configuration to set up a sequencing - operation, it will instantiate the &StreamSequencer; class and will call a JavaBean-style setter method for each property. - For example, calling setProperty("foo","val1") on the sequencer configuration will mean that ModeShape - will instantiate the sequencer implementation and will look for a setFoo(String) method on the sequencer implementation - class, and use that method (if found) to pass the "val1" value to the instance. + + Each time sequencer(String) is called, it will either load the existing definition with the supplied + name or will create a new definition if one does not already exist. To remove a definition, simply call remove() + on the result of sequencer(String). + The set of existing definitions can be accessed with the sequencers() method. - - - MIME Type Detectors - Each defined MIME type detector must specify the name of the &MimeTypeDetector; implementation class as well as any - other bean properties required by the implementation. - + Note that in addition to including a description for the configuration, it is also possible to set sequencer-specific properties + using the setProperty(String,String[]) method. When ModeShape uses this configuration to set up a sequencing + operation, it will instantiate the &StreamSequencer; class and will call a JavaBean-style setter method for each property. + For example, calling setProperty("foo","val1") on the sequencer configuration will mean that ModeShape + will instantiate the sequencer implementation and will look for a setFoo(String) method on the sequencer implementation + class, and use that method (if found) to pass the "val1" value to the instance. + + + + MIME Type Detectors + Each defined MIME type detector must specify the name of the &MimeTypeDetector; implementation class as well as any + other bean properties required by the implementation. + - - Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from - the classpath or from a specific classpath). - - - Each time mimeTypeDetector(String) is called, it will either load the existing definition with the supplied - name or will create a new definition if one does not already exist. To remove a definition, simply call remove() - on the result of mimeTypeDetector(String). - The set of existing definitions can be accessed with the mimeTypeDetectors() method. - - - - - - Storing Configuration + .usingClass(org.modeshape.graph.mimetype.ExtensionBasedMimeTypeDetector.class); +]]> - Regardless of how the &JcrConfiguration; is loaded, it can also be stored to a file or stream in an XML format that can then be - reloaded in the future to recreate the configuration. This makes it very easy to programmatically generate a configuration file - once while being able to load that same configuration at a later time (or on a different instance). + Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from + the classpath or from a specific classpath). - + Each time mimeTypeDetector(String) is called, it will either load the existing definition with the supplied + name or will create a new definition if one does not already exist. To remove a definition, simply call remove() + on the result of mimeTypeDetector(String). + The set of existing definitions can be accessed with the mimeTypeDetectors() method. + + + + + Storing Configuration + + Regardless of how the &JcrConfiguration; is loaded, it can also be stored to a file or stream in an XML format that can then be + reloaded in the future to recreate the configuration. This makes it very easy to programmatically generate a configuration file + once while being able to load that same configuration at a later time (or on a different instance). + + - - This will create a file at pathToFile that contains the current configuration in XML format. Any changes made after - the most recent call to the save() method on the &JcrConfiguration; object will not be saved in the configuration - repository, and thus will not be in the generated file. The generated XML will not be formatted to maximize human readability. - - - - - JcrRepositoryFactory +]]> - ModeShape provides the &JcrRepositoryFactory; class, an implementation of the &RepositoryFactory; interface, that can return a reference to a named repository - based on a provided configuration file. In addition to providing the getRepository(Map) method from the - JSR-283 API, ModeShape also provides an extended API for this class in the org.modeshape.jcr.api.RepositoryFactory interface. + This will create a file at pathToFile that contains the current configuration in XML format. Any changes made after + the most recent call to the save() method on the &JcrConfiguration; object will not be saved in the configuration + repository, and thus will not be in the generated file. The generated XML will not be formatted to maximize human readability. - - Accessing Repositories from Configuration Files - - The simplest way to use the &JcrRepositoryFactory; to access a &Repository; is to provide it a URL that points to a configuration file. - This can be done with the following sample code: - - - - Alternatively, if you know that you will be using ModeShape as your JCR API in the future and want to condense code at the expense of tighter coupling, you can - instantiate a &JcrRepositoryFactory; directly. - - - - The value of configUrl in the code snippets above would be something like file:relativePathToConfigFile?repositoryName=yourRepositoryName. - In this example, the configuration file that specifies the repository setup will be loaded from the file path relativePathToConfigFile and - the repository named yourRepositoryName will be returned. If there is no repository with that name or the configuration file does not exist - at that path, getRepository(Map) will return null. The format for the configuration file is the same as used above - when loading a &JcrConfiguration; object from a configuration file. - - - If an absolute path to the configuration file works better, a value for configUrl like file:///absolutePathToConfigFile?repositoryName=yourRepositoryName - could have been used instead. Note the addition of the three forward slashes after the protocol portion of the URL (i.e., file:). this indicates that the - following path is an absolute path. - - - This method can be used to load files from the file system or from the classpath. If there is no file found at the given path, the same path will be used to try - to load the configuration file as a resource through the classloader. - - - Behind the scenes, the &JcrRepositoryFactory; is checking to see if it has already configured and started a &JcrEngine; for the named configuration file. If it - has already created a &JcrEngine; for this configuration, then that &JcrEngine; is reused. Otherwise, a new &JcrEngine; is created and configured based on the given - configuration file. Either way, the &JcrEngine; is used to get the reference to the returned &Repository;. - - - - Accessing Repositories from JNDI - - Given a slightly different URL, the same code used above can be reused to get a &Repository; from a &JcrEngine; that has been previously deployed through JNDI. - JNDI URLs take the form jndi:///nameOfJndiResource?repositoryName=yourRepositoryName. The nameOfJndiResource is passed directly to - a JNDI lookup. If no &JcrEngine; exists at the given name, the getRepository(Map) method will return null. Also, any additional - parameters besides JcrRepositoryFactory.URL that are provided in the parameters map in the getRepository(Map) method will be used - in the constructor for the InitialContext used to look up the JNDI reference. - - - Accessing a repository through JNDI differs slightly from accessing a repository from a configuration file in that the &JcrRepositoryFactory; will never create a - new &JcrEngine; instance in response to a getRepository invocation with a JNDI URL. - - - - Cleaning Up after JcrRepositoryFactory - - As a preceding section notes, it is possible for the &JcrRepositoryFactory; to create one or more &JcrEngine; instances. Although the - JSR-283 specification does not specify a way to shutdown engines or repositories created as a side effect of &JcrRepositoryFactory; use, ModeShape has an extension to the - JSR-283 API that provides this capability. - - + + + Loading from a Configuration Repository + + Loading the ModeShape configuration from an existing repository is also pretty straightforward. Simply create and configure the + &RepositorySource; instance to point to the desired repository, and then call the loadFrom(&RepositorySource; source) + method: + + - - The code listed above will instantiate a new JcrRepositoryFactory and use a ModeShape-specific method to shutdown any &JcrEngine;s created by &JcrRepositoryFactory; - and wait for up to 30 seconds for each of them to shutdown gracefully. Behind the scenes, the shutdown(long, TimeUnit) method is iterating over an internal - collection of &JcrEngine;s and calling shutdown and awaitTermination(long, TimeUnit) on each engine. + + This really is a more advanced way to define your configuration, so we won't go into how you configure a &RepositorySource;. + + + The loadFrom(...) method can be called any number of times, but each time it is called it completely wipes + out any current notion of the configuration and replaces it with the configuration found in the file. - - - + + + There is an optional second parameter that defines the name of the workspace in the supplied source where the configuration content + can be found. It is not needed if the workspace is the source's default workspace. + There is an optional third parameter that defines the &Path; within the configuration repository identifying the parent node of the various + configuration nodes. If not specified, it assumes "/". This makes it possible for the configuration content to be + located at a different location in the hierarchical structure. (This is not often required, but when it is required + this second parameter is very useful.) + + + Deploying ModeShape via JNDI @@ -529,7 +347,6 @@ repoFactory.shutdown(30, TimeUnit.SECONDS); and then close the session when completed. - - - Using ModeShape via Maven + + Setting the Classpath - ModeShape is a Maven-based project. If your application is using Maven, it is very easy to add a dependency on - ModeShape's JCR library (plus any extensions), and Maven will ensure your application has access to all - of the ModeShape artifacts and all 3rd-party libraries upon which ModeShape depends. - Simply add a dependency in your application's POM: + Before you deploy ModeShape into your application or its environment, you need to make sure that all of the ModeShape + JARs are on the appropriate classpath. Two different scenarios are covered in this section: Maven-based, and using + JARs with the traditional classpath. + + Building against ModeShape via Maven + + By far the easiest way to use ModeShape is to use Maven, because with just a few lines of code, Maven will automatically + pull all the JARs and source for all of the ModeShape libraries as well as everything those libraries need. + All of ModeShape's artifacts for each release are published in the new JBoss Maven repository + under the "org.modeshape" group ID. + + + Using the JBoss Maven repository + + The JBoss Maven repository not only contains all of the artifacts for ModeShape and other open source projects + hosted at JBoss.org, but it also + proxies quite a few other repositories that contain many other third-party + libraries. + + + So if you're using Maven (or Ivy), first make sure your project knows about this new JBoss Maven repository. + One way to do this is to add the following to your project POM (you'll still likely want to use other Maven repositories + for third-party artifacts): + + + + jboss + http://repository.jboss.org/nexus/content/groups/public/ + + +]]> + + Or, you can add this information to your ~/.m2/settings.xml file. For more information, + see the JBoss wiki page. + + + + Add dependency to ModeShape + + Then, simply modify your project's POM by adding dependencies on the ModeShape JCR library: + org.modeshape modeshape-jcr - 1.1.0.Final + 2.0.0.Final + +]]> + + This adds only the minimal libraries required to use ModeShape, so you need to add dependencies for + each of the connectors and sequencers you want to use. Here is the list of available sequencers: + + + org.modeshape + modeshape-sequencer-cnd + 2.0.0.Final + + + org.modeshape + modeshape-sequencer-ddl + 2.0.0.Final + + + org.modeshapce + modeshape-sequencer-images + 2.0.0.Final + + + org.modeshape + modeshape-sequencer-classfile + 2.0.0.Final + + + org.modeshape + modeshape-sequencer-java + 2.0.0.Final + + + org.modeshape + modeshape-sequencer-mp3 + 2.0.0.Final + + + org.modeshape + modeshape-sequencer-msoffice + 2.0.0.Final + + + org.modeshape + modeshape-sequencer-xml + 2.0.0.Final + + + org.modeshape + modeshape-sequencer-text + 2.0.0.Final + + + org.modeshape + modeshape-sequencer-zip + 2.0.0.Final ]]> - plus dependencies for each optional extension (sequencers, connectors, MIME type detectors, etc.): + Here is the list of available connectors: - org.modeshape - modeshape-connector-store-jpa - 1.1.0.Final + org.modeshape + modeshape-connector-filesystem + 2.0.0.Final -... - org.modeshape - modeshape-sequencer-java - 1.1.0.Final + org.modeshape + modeshape-connector-infinispan + 2.0.0.Final + + + org.modeshape + modeshape-connector-jcr + 2.0.0.Final + + + org.modeshape + modeshape-connector-jbosscache + 2.0.0.Final + + + org.modeshape + modeshape-connector-jdbc-metadata + 2.0.0.Final + + + org.modeshape + modeshape-connector-store-jpa + 2.0.0.Final + + + org.modeshape + modeshape-connector-svn + 2.0.0.Final +]]> + + The sequencer and connector libraries you choose, plus every third-party library they need, will be pulled in automatically + by Maven into your project. + + + + Add dependencies for logging + + ModeShape is designed to use the same logging framework as your application, and it uses SLF4J to accomplish this. + In other words, ModeShape depends upon the SLF4J API library, but requires you to provide provide a logging implementation + as well as the appropriate SLF4J binding JAR. + + + For example, if your application is using Log4J, your application will already have a dependency + for it, and so ModeShape log messages will be sent to the same logging system used in your application, you need to add a + dependency to the SLF4J-to-Log4J binding JAR: + + + org.slf4j + slf4j-log4j12 + 1.5.11 + + + log4j + log4j + 1.2.16 ]]> - - Then, continue by defining a &JcrConfiguration; and building the engine, as discussed earlier. - This is very straightforward, and this is exactly what the ModeShape examples do. - - + + Of course, SLF4J works with other logging frameworks, too. Some logging implementations (such as LogBack) + implement the SLF4J API natively, meaning they require no binding JAR. For details on the options and how to configure them, see the + SLF4J manual. + + + + + Building against ModeShape via JARs - The ModeShape community has solicited input on how we can make it easier to consume and use ModeShape in applications - that do not use Maven. Check out the discussion thread, - and please add any suggestions or opinions! + If your application doesn't use Maven, you'll need to obtain the ModeShape JARs and place them onto your application's classpath. + ModeShape provides a single download with all of the JARs for all ModeShape components + and all dependencies. This file contains the following: + + + + modeshape-jcr-&versionNumber;-with-dependencies.jar contains the JARs + necessary to run the core ModeShape JCR repository engine, + the in-memory connector, and the federating connector; + + + + + one modeshape-connector-<type>-&versionNumber;-with-dependencies.jar + for each type of connector, each containing the JARs necessary + for that connector; + + + + + one modeshape-sequencer-<type>-&versionNumber;-with-dependencies.jar + for each type of sequencer, each containing the JARs necessary + for that sequencer; + + + + + modeshape-mimetype-detector-aperture-&versionNumber;-with-dependencies.jar + contains all of the JARs required for the component that detects + the MIME type of files based upon names and/or content; and + + + + + modeshape-jpa-ddl-gen-&versionNumber;-jar-with-dependencies.jar + contains all of the JARs required to run the DDL generation utility. + + + + Note that the core engine is required in all configurations. The jcr-2.0.jar file is not included and must be provided by you. + And, as mentioned in the previous section, ModeShape uses SLF4J for logging and you must provide + a logging implementation as well as the appropriate SLF4J binding JAR. - + What's next - This chapter outlines how you configure ModeShape, how you then access a javax.jcr.Repository instance, - and use the standard JCR API to interact with the repository. The - next chapter talks about using the JCR API with your ModeShape repository. + This chapter outlines how you configure ModeShape, how to deploy ModeShape into your application, and how to set up your application's environment + with the required ModeShape JARs. + The next chapter talks about how your application can use the JCR API to access ModeShape repositories. Index: docs/reference/src/main/docbook/en-US/content/jcr/deploying_modeshape_jcr.xml deleted file mode 100644 =================================================================== --- docs/reference/src/main/docbook/en-US/content/jcr/deploying_modeshape_jcr.xml (revision 1911) +++ /dev/null (working copy) @@ -1,100 +0,0 @@ - - - -%CustomDTD; -]> - - Deploying the ModeShape JCR Implementation - - Placeholder for the ModeShape REST Server documentation - - - ModeShape JCR Deployment Models - - One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components - require this context to be passed into individual methods, allowing the context to vary with each method invocation. - Other components require the context to be provided before it's used, and will use that context for all its operations - (until it is given a different one). - - - - Understanding JCR Security in ModeShape - - One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components - require this context to be passed into individual methods, allowing the context to vary with each method invocation. - Other components require the context to be provided before it's used, and will use that context for all its operations - (until it is given a different one). - - - - Configuring Security - - One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components - require this context to be passed into individual methods, allowing the context to vary with each method invocation. - Other components require the context to be provided before it's used, and will use that context for all its operations - (until it is given a different one). - - - - Configuring the Repositories - - One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components - require this context to be passed into individual methods, allowing the context to vary with each method invocation. - Other components require the context to be provided before it's used, and will use that context for all its operations - (until it is given a different one). - - - Choosing the Correct Connectors - - One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components - require this context to be passed into individual methods, allowing the context to vary with each method invocation. - Other components require the context to be provided before it's used, and will use that context for all its operations - (until it is given a different one). - - - - - Configuring ModeShape Core - - One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components - require this context to be passed into individual methods, allowing the context to vary with each method invocation. - Other components require the context to be provided before it's used, and will use that context for all its operations - (until it is given a different one). - - - - Smoke Testing the Installation - - One such implementation is the &JaasSecurityContext;, which delegates any authentication or authorization requests to a - Java Authentication and Authorization Service (JAAS) - provider. This is the standard approach for authenticating and authorizing in Java, and is the default mechanism - used by the &JcrEngine;. - - - - Index: docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml (working copy) @@ -32,49 +32,468 @@ Using the JCR API with ModeShape The - Content Repository for Java technology API + Content Repository for Java Technology API 2.0 provides a standard Java API for working with content repositories. Abbreviated "JCR", this API was developed as part of the - Java Community Process under JSR-170 (JCR 1.0) and has been revised under JSR-283. - ModeShape provides a partial JCR 1.0 implementation that allows you to work with the contents of a repository using the - JCR API. For information about how to use the JCR API, please see the JSR-170 specification. + Java Community Process under JSR-170 (JCR 1.0) and has been revised as JCR 2.0 under JSR-283. + JCR 2.0 is largely This improved version of the JCR API is largely the same as JCR + Some of the improvements make it possible for your application to be written entirely against the JCR 2.0 API + + + ModeShape implements the JCR 2.0 API, meaning your application implementation that allows you to work with the contents of a repository using the + JCR API. + - In the interests of brevity, this chapter does not attempt to reproduce the JSR-170 specification nor provide - an exhaustive definition of ModeShape JCR capabilities. Rather, this chapter will describe any deviations from the - specification as well as any ModeShape-specific public APIs and configuration. + + In the interests of brevity, this chapter does not attempt to reproduce the JSR-283 specification nor provide + an exhaustive definition of ModeShape JCR capabilities. Rather, this chapter will describe any deviations from the + specification as well as any ModeShape-specific public APIs and configuration. So, for a detailed explanation + of the JCR API and its many interfaces and methods, see the JSR-283 specification. - - Using ModeShape within your application is actually quite straightforward. As you'll see in this chapter, - the first step is setting up ModeShape and starting the JcrEngine. After that, you obtain the - javax.jcr.Repository instance for a named repository and just use the standard JCR API throughout your - application. + + Using ModeShape within your application is actually quite straightforward, and with JCR 2.0 it is possible for your + application to do everything using only the JCR 2.0 API. Your application will first obtain a javax.jcr.Repository instance, + and will use that object to create sessions through which your application will read, modify, search, + or monitor content in the repository. + JCR sessions are designed to be lightweight, so it is perfectly fine + (and actually recommended) for your application to create many short-lived sessions while generally avoiding + longer-lived sessions. In fact, javax.jcr.Session objects are not required to be thread-safe + (and are not in ModeShape), so your application should avoid using a single Session instance in multiple threads. - - Obtaining JCR Repositories - Once you've obtained a reference to a JcrEngine as described in - the previous chapter, obtaining a repository is as easy as calling - the getRepository(String) method with the name of the repository that you just configured. - -&String; repositoryName = ...; -&JcrEngine; jcrEngine = ...; -&Repository; repository = jcrEngine.getRepository(repositoryName); - - At this point, your application can proceed by working with the JCR API. + + What's new in JCR 2.0? + + Before we get started talking about how to use ModeShape via the standard JCR 2.0 API, it's worth spending a little time talking + about the changes in JCR 2.0 compared with version 1.0. + + First the good news. If your application was written against the JCR 1.0 API, there's a good chance that most functionality will + still work. Generally speaking, many of the methods + Although an application written against the JCR 1.0 API will for the most part work very well against a JCR 2.0 repository, there are + a few improvements to the JCR 2.0 API that your application will likely want to leverage. + + + Let's look at some of the more important changes in the JCR 2.0 API. However, this is certainly not definitive nor a complete + comparison, so please consult the JSR-283 specification. + + + Connecting + + JCR 1.0 did not specify a way for client applications to obtain the &Repository; instance, though the JCR 1.0 specification did + state this is typically done through JNDI. Consequently, JCR clients either used the JNDI approach or were required to use + implementation-specific code. Often, client applications abstracted this process to minimize their reliance upon implementation-specific + interfaces. + + + While the JNDI approach still works, JCR 2.0 introduces a new mechanism that makes it possible to find a &Repository; instance + using only the JCR API. Details of this are covered more in later, but suffice + to say that ModeShape does support this new &RepositoryFactory; approach. + + + How this affects your application: If your application used an implementation-specific approach to obtaining + a &Repository; instance, you might consider changing it to use the + new &RepositoryFactory; mechanism. + + + + Identifiers + + JCR 1.0 used the notion of UUIDs on referenceable nodes - in other words those nodes with the "mix:referencedable" mixin. + However, there were several disadvantages to this design. First, non-referenceable nodes had no such identifier in the JCR API, + leading to difficulties in easily identifying nodes using an immutable and invariant identifier (unlike the path, which can change + at any time) and requiring a fair amount of code to check whether a node is referenceable before its UUID could safely be obtained. + Second and perhaps more importantly, only valid UUIDs could be used to identify nodes. This can cause difficulty + when JCR is used as an API to another system that does not use UUIDs. + + + JCR 2.0 introduces the notion of an identifier on all nodes, and the format of this identifier is designed to be opaque to the + client applications. This dramatically reduces the code to access a node's identifier down to a simple method call. And it + makes it possible for an implementation to use any identifiers format. This is good for ModeShape federation, as connectors + no longer need to force UUIDs for all nodes. + + + How this affects your application: The Node.getUUID() method is now deprecated, and instead + your code should call Node.getIdentifier(), which works on any node. However, be aware that the resulting identifier + is no longer required to be a valid UUID. ModeShape does support these methods and behavior. + + + + Binary Values + + JCR 1.0 has always supported storing binary values in properties, but clients could do little more than just stream the bytes + for each value. JCR 2.0 introduces a &Binary; interface that defines a way to get the size of the binary value, an InputStream + to the value, a method for random access to the value's bytes, and a way to dispose of the binary value when completed + (allowing the implementation to better clean up memory and other resources). + + + How this affects your application: The way your existing JCR application accesses and sets binary values + will still work, but the methods are now deprecated. Therefore, you will very likely want to change to use the new &Binary; interface. + For example, code that previously accessed the input stream directly from the &Property;: + + + + can be minimally changed to first get the &Binary; value and then get the stream from this Binary value: + + + + This second example is not using any deprecated methods, but does not actually dispose of the &Binary; object. This actually + works just fine in ModeShape, as closing the InputStream will automatically dispose of the &Binary; object. + + + You may also consider whether your application may benefit from the new Binary.getSize() or Binary.read(byte[],long) methods. + + + + Node Type Management + + In JCR 1.0, client applications could discover node types, property definitions, and child node definitions, but the API did not + provide a way for client applications to modify or create new node types. This has been rectified in the JCR 2.0 API, and is + these methods are now supported by ModeShape. + + + Additionally, the JCR 2.0 specification formalized the Compact Node Definition grammar, and made a few minor + improvements to the CND formats used in some JCR 1.0 implementations. Earlier ModeShape releases supported the older CND format, + and ModeShape &versionNumber; now supports the grammar as defined in the specification. + + + How this affects your application: Your application can now define its node types using the standard + CND format and/or using the new programmatic mechanism. If you already used the older CND format, be aware of the few new + options available when defining property definitions (e.g., searchable, queryable, etc.). Note that node type discovery is + largely unchanged. + + + + Queries + + JCR 1.0 made it possible for applications to query the repository using XPath and JCR-SQL query languages. JCR 2.0 maintains + the (mostly) similar Java interfaces for executing queries, but it deprecates the XPath and JCR-SQL query languages + and introduces a new declarative language called "JCR-SQL2" that is a very good improvement over JCR-SQL. JCR 2.0 also + introduces a new query object model (called "JCR-QOM") for defining queries using a programmatic API. + + + ModeShape supports all of these languages (XPath, + JCR-SQL, JCR-SQL2, + JCR-QOM), and also supports a + full-text query language + that is defined by the full-text search expression in the JCR-SQL2 language. Additionally, ModeShape extends most of these + languages to support richer and more capable queries. + + + How this affects your application: Your application can continue to use XPath and JCR-SQL queries. + However, your application may benefit from switching from JCR-SQL to JCR-SQL2 and its greater capabilities and expressive + power. Leverage some of the ModeShape extensions to make your JCR-SQL2 queries even more powerful. + + + + Workspace Management + + Applications could not use the JCR 1.0 API to create or destroy workspaces, meaning such operations could only be done through + a non-standard and implementation-specific API. The JCR 2.0 API now standardizes these operations, and although not all + implementations are required to support them, ModeShape does support these (though not all connectors do support them). + + + How this affects your application: Your application can now create and remove workspaces using the standard JCR 2.0 API. + + + + Observation + + Applications could use the JCR 1.0 API to be notified of changes to the content, using the optional observation feature. + called "observation". create or destroy workspaces, meaning such operations could only be done through + a non-standard and implementation-specific API. The JCR 2.0 API now standardizes these operations, and although not all + implementations are required to support them, ModeShape does support these (though not all connectors do support them). + + + How this affects your application: Your application can now create and remove workspaces using the standard JCR 2.0 API. + + + + Locking + + JCR 1.0 API had the notion of locking nodes, useful in situations that required synchronization around reading and modifying + content. This optional API is simple and clean, and worked quite well. The JCR 2.0 API preserved all of the JCR 1.0 locking semantics, + but added a few (optional) methods. ModeShape implements this optional locking feature. + + + How this affects your application: If your application is already using the JCR 1.0 locking feature, + be aware that many of the locking-related methods on &Node; were deprecated in JCR 2.0 and moved to the new &LockManager; interface. + However, locking semantics remain unchanged. + + + + Versioning + + Versioning of nodes was defined as an optional feature of the JCR 1.0 API. The JCR 2.0 API expanded upon locking by defining + a simple versioning model, introducing the &VersionManager; interface, and making some semantic changes as well. For example, + restoring a version that contained a versioned child in its subgraph no longer automatically restores the versioned child. + This behavior was ambiguous in the JCR 1.0 specification, and ModeShape 1.x performed the restore operation recursively down the graph. + The JCR 2.0 specification more clearly requires a non-recursive restore. Therefore, ModeShape &versionNumber; now supports + the "full versioning" model. + + + How this affects your application: If your application is already using JCR 1.0 versioning feature, + be aware that many of the version-related methods on &Node; were deprecated in JCR 2.0 and moved to the new &VersionManager; interface. + And any reliance upon ModeShape's recursive restore operation must be changed, per the JCR 2.0 specification. + + + + Importing and Exporting + + Importing and exporting content is largely unchanged in JCR 2.0, with the exception of specific requirements on handling + node identifiers. + + + How this affects your application: Exporting from a JCR 1.0 or 2.0 repository and importing into a JCR 2.0 repository + should work as before. ModeShape does support importing and exporting. + + + + Orderable Child Nodes + + Orderable child nodes was an optional feature in JCR 1.0, and has been carried over to JCR 2.0 unchanged. Node ordering has been supported + by ModeShape since the initial release. + + + How this affects your application: No changes are required if your application relies upon node ordering. + + + + Paths + + As defined in JCR 1.0, paths only consisted of segments with node names. JCR 2.0 adds a new form of path called "identifier paths" that + are of the form '[' identifier ']', where identifier is an opaque + identifier. (Note that the JCR 2.0 specification might appear to allow identifier segments and name segments to be used together, but + Section 3.4.1.1 requires that an identifier segment must be the first and only segment in a path.) + + + How this affects your application: Any application written to JCR 1.0 paths will likely work as expected (this is + certainly true when using ModeShape repositories). However, with JCR 2.0 it is now possible for your application to start making us + of identifier paths. For example, PATH properties can now store identifier paths, and it is possible to resolve an identifier path + to the actual node. And while the specification does not preclude an implementation returning an identifier path as the node's + absolute path, ModeShape never does this and will always return the name-oriented path. + + + + getItem(String) + + The JCR 1.0 specification was slightly ambiguous in defining how the getItem(String) method behaved if the relative path + could resolve to a node or a property. ModeShape always implemented this by first attempting to resolve to a node, and only if no + such node could be found would it attempt to resolve to a property. The JCR 2.0 specification now explicitly specifies this behavior + (see Section 3.4.2.2). + + + How this affects your application: Your application will need to change if it uses getItem(String) and + expects relative paths to be resolved against properties before nodes, as this is clearly different from the JCR 2.0 specified behavior. + Otherwise, your application needs no changes with respect to getItem(String). + + + + Obtaining a JCR Repository + + Before your application can use a JCR repository, it has to find it. As mentioned above, + the JCR 2.0 API defines a new &RepositoryFactory; interface that can be used with the + Java Standard Edition Service Loader mechanism + to obtain a &Repository; instance, all using the JCR API alone: + + parameters = ... +Repository repository = null; +for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) { + repository = factory.getRepository(parameters); + if (repository != null) break; +}]]> + + This code looks for all &RepositoryFactory; implementations on the classpath (assuming those implementations properly defined the service provider + within their JARs), and will ask each to create a repository given the supplied parameters. Thus, the parameters + are specific to the implementation you want to use. + + + + With JCR 1.0, applications could only find a &Repository; instance using implementation-specific code. + This new JCR 2.0 approach is a bit more complicated, but should work with most JCR 2.0 implementations + and does not require using any implementation classes. And your application can even load the parameters + from a configuration resource, meaning nothing in your application depends on a particular JCR implementation. + + + + ModeShape uses a single property named "org.modeshape.jcr.URL" + with a value that is a URL that either resolves to a ModeShape configuration file, such as + + + + or points to a &JcrEngine; instance in JNDI: + + + + Pointing directly to a configuration file often works well in stand-alone applications, while using JNDI works great + for applications deployed to server platforms (e.g., an application server or servlet container) where multiple applications + might want to use the same JCR repository. (We'll see in the next section + how to configure ModeShape's &JcrEngine; explicitly and register it in JNDI.) + + + So, here's the ServiceLoader example again, but with ModeShape-specific parameters: + + parameters = Collections.singletonMap("org.modeshape.jcr.URL", configUrl); + +Repository repository = null; +for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) { + repository = factory.getRepository(parameters); + if (repository != null) break; +}]]> + + Once you've gotten hold of a &Repository; instance, you can use it to create &Session;s, using code similar to: + + + + We'll talk about the various ways of creating sessions in a later chapter. + + + URL formats + + The value of configUrl in the code snippets above would be something like file:relativePathToConfigFile?repositoryName=yourRepositoryName. + In this example, the configuration file that specifies the repository setup will be loaded from the file path relativePathToConfigFile and + the repository named yourRepositoryName will be returned. If there is no repository with that name or the configuration file does not exist + at that path, getRepository(Map) will return null. The format for the configuration file is the same as used above + when loading a &JcrConfiguration; object from a configuration file. + + + If an absolute path to the configuration file works better, a value for configUrl like file:///absolutePathToConfigFile?repositoryName=yourRepositoryName + could have been used instead. Note the addition of the three forward slashes after the protocol portion of the URL (i.e., file:). this indicates that the + following path is an absolute path. + + + This method can be used to load files from the file system or from the classpath. If there is no file found at the given path, the same path will be used to try + to load the configuration file as a resource through the classloader. + + + Behind the scenes, the &JcrRepositoryFactory; is checking to see if it has already configured and started a &JcrEngine; for the named configuration file. If it + has already created a &JcrEngine; for this configuration, then that &JcrEngine; is reused. Otherwise, a new &JcrEngine; is created and configured based on the given + configuration file. Either way, the &JcrEngine; is used to get the reference to the returned &Repository;. + + + + Accessing Repositories from JNDI + + Given a slightly different URL, the same code used above can be reused to get a &Repository; from a &JcrEngine; that has been previously deployed through JNDI. + JNDI URLs take the form jndi:///nameOfJndiResource?repositoryName=yourRepositoryName. The nameOfJndiResource is passed directly to + a JNDI lookup. If no &JcrEngine; exists at the given name, the getRepository(Map) method will return null. Also, any additional + parameters besides JcrRepositoryFactory.URL that are provided in the parameters map in the getRepository(Map) method will be used + in the constructor for the InitialContext used to look up the JNDI reference. + + + Accessing a repository through JNDI differs slightly from accessing a repository from a configuration file in that the &JcrRepositoryFactory; will never create a + new &JcrEngine; instance in response to a getRepository invocation with a JNDI URL. + + + + Cleaning Up after JcrRepositoryFactory + + As a preceding section notes, it is possible for the &JcrRepositoryFactory; to create one or more &JcrEngine; instances. Although the + JSR-283 specification does not specify a way to shutdown engines or repositories created as a side effect of &JcrRepositoryFactory; use, ModeShape has an extension to the + JSR-283 API that provides this capability. + + + + The code listed above will instantiate a new &JcrRepositoryFactory; and use a ModeShape-specific method to shutdown any &JcrEngine;s created by &JcrRepositoryFactory; + and wait for up to 30 seconds for each of them to shutdown gracefully. Behind the scenes, the shutdown(long, TimeUnit) method is iterating over an internal + collection of &JcrEngine;s and calling shutdown and awaitTermination(long, TimeUnit) on each engine. + + + + + ModeShape's JcrEngine + + Although the preferred mechanism to obtain a &Repository; object is through the &RepositoryFactory; interface + described above, there are times when an application wants + or needs to have more control over an actual ModeShape engine, which encapsulates everything necessary + to run one or more JCR repositories and managing the underlying repository sources, the pools of connections to the sources, the sequencers, + the MIME type detector(s), and the &Repository; implementations. + + + Creating a new &JcrEngine; instance is very easy if you already have a valid &JcrConfiguration; instance as + described in the previous chapter. Once you have a valid &JcrConfiguration; + instance, all you have to do is build and start the engine: + + + + Obtaining a JCR &Repository; instance is a matter of simply asking the engine for it by the name defined in the configuration: + + + + At this point, your application can proceed by working with the JCR API. + + + And, once you're finished with the &JcrEngine;, you should shut it down: + + + + When the shutdown() method is called, the &Repository; instances managed by the engine are marked as being shut down, + and they will not be able to create new &Session;s. However, any existing &Session;s or ongoing operations (e.g., event notifications) + present at the time of the shutdown() call will be allowed to finish. + In essence, shutdown() is a graceful request, and since it may take some time to complete, + you can wait until the shutdown has completed by simply calling awaitTermination(...) as shown above. + This method will block until the engine has indeed shutdown or until the supplied time duration has passed (whichever comes first). + And, yes, you can call the awaitTermination(...) method repeatedly if needed. + + Creating JCR Sessions - Once you have obtained a reference to the JCR &Repository;, you can create a JCR session using one of its - login(...) methods. The JSR-170 specification provides four login methods, but the + + Once you have obtained a reference to the JCR &Repository;, you can create a JCR session using one of its + login(...) methods. The JSR-283 specification provides four login methods, but the behavior of these methods depends on the kind of authentication system your application is using. Using JAAS - The login() method allows the implementation to choose its own security context to create a session in the default workspace - for the repository. The ModeShape JCR implementation uses the security context from the current JAAS &AccessControlContext;. This implies - that this method will throw a &LoginException; if it is not executed as a &PrivilegedAction; (AND the - JcrRepository.Options.ANONYMOUS_USER_ROLES option does not allow access - see below for an example of how to configure guest user access). - Here is one example of how this might work: + + The login() method allows the implementation to choose its own security context to create a session in the default workspace + for the repository. The ModeShape JCR implementation uses the security context from the current JAAS &AccessControlContext;. This implies + that this method will throw a &LoginException; if it is not executed as a &PrivilegedAction; (AND the + JcrRepository.Options.ANONYMOUS_USER_ROLES option does not allow access; + see below for an example of how to configure guest user access). + Here is one example of how this might work: + Subject subject = ...; &Session; session = Subject.doAsPrivileged(subject, new PrivilegedExceptionAction<&Session;>() { @@ -83,7 +502,9 @@ Subject subject = ...; } }, AccessController.getContext()); + Another variant of this is to use the AccessControlContext directly, which then operates against the current Subject: + &Session; session = AccessController.doPrivileged( new PrivilegedExceptionAction<&Session;>() { public Session run() throws Exception { @@ -91,10 +512,10 @@ Subject subject = ...; } }); - Either of these approaches will yield a session with the same user name and roles as subject. The login(String workspaceName) method is comparable and allows the workspace to be specified by name: + Subject subject = ...; final &String; workspaceName = ...; @@ -103,26 +524,30 @@ final &String; workspaceName = ...; return repository.login(workspaceName); }}, AccessController.getContext()); - The JCR API also allows supplying a JCR &Credentials; object directly as part of the login process, although ModeShape imposes some requirements on what types of &Credentials; may be supplied. The simplest way is to provide a JCR &SimpleCredentials; object. These credentials will be validated against the JAAS realm named "modeshape-jcr", unless another realm name is provided as an option during the JCR repository configuration. For example: + &String; userName = ...; char[] password = ...; &Session; session = repository.login(new &SimpleCredentials;(userName, password)); + Similarly, the login(Credentials credentials, String workspaceName) method enables passing the credentials and a workspace name: + &String; userName = ...; char[] password = ...; &String; workspaceName = ...; &Session; session = repository.login(new &SimpleCredentials;(userName, password), workspaceName); + If a &LoginContext; is available for the user, that can be used as part of the credentials to authenticate the user with ModeShape instead. This snippet uses an anonymous class to provide the login context, but any class with a &LoginContext; getLoginContext() method can be used as well. + final &LoginContext; loginContext = ...; &Session; session = repository.login(new &Credentials;() { @@ -131,7 +556,6 @@ final &LoginContext; loginContext = ...; } }, workspaceName); - Using Custom Security @@ -178,13 +602,13 @@ final &LoginContext; loginContext = ...; the JcrRepository.Options.ANONYMOUS_USER_ROLES option for your repository to have a different value, like "" (to disable guest access entirely) or "readonly" (to give guests read-only access to all repositories). The value of this option can be any pattern that matches those described in the table below. + The Using ModeShape chapter of the Getting Started Guide provides examples of modifying this option through programmatic configuration or in an XML configuration file. - @@ -200,16 +624,14 @@ final &LoginContext; loginContext = ...; Level 1 and Level 2 (Required) Features ModeShape currently supports all Level 1 and Level 2 features defined by the - JSR-170 specification. + JSR-283 specification. Optional Features - ModeShape also supports the optional JCR locking, observation, query, and versioning features. - However, ModeShape's behavior with regard to events upon deletion follows the updated behavior - outline in the JSR-283 specification (namely that when a subgraph - is deleted, ModeShape generates only one event for the top-level node in that subgraph). + ModeShape also supports the optional JCR locking, observation, query, and full versioning features, + as well as most of the node type management features. ModeShape now supports the optional SQL query feature as defined by JSR-170 @@ -224,7 +646,7 @@ final &LoginContext; loginContext = ...; JCR Security - Although the JSR-170 specification requires implementation of the Session.checkPermission(String, String) method, + Although the JSR-283 specification requires implementation of the Session.checkPermission(String, String) method, it allows implementors to choose the granularity of their access controls. ModeShape supports coarse-grained, role-based access control at the repository and workspace level. @@ -317,16 +739,17 @@ final &LoginContext; loginContext = ...;
+ In this release, ModeShape does not check that the actions parameter passed into Session.checkPermission(...) contains only valid actions. This check may be added in a future release. - - It is also possible to grant access only to one or more repositories on a single ModeShape server or to one or more named workspaces within a repository. The format for - role names is defined below: - + + It is also possible to grant access only to one or more repositories on a single ModeShape server or to one or more named workspaces within a repository. The format for + role names is defined below: + Role Formats @@ -364,25 +787,25 @@ final &LoginContext; loginContext = ...; and read/write access to any workspace in a staging repository. - As a final note, the ModeShape JCR implementation may have additional security roles added prior to the 1.0 release. A CONNECT role + As a final note, the ModeShape JCR implementation may have additional security roles added in the future. A CONNECT role is already being used by the ModeShape REST Server to control whether users have access to the repository through that means. Built-In Node Types - ModeShape supports all of the built-in node types described in the JSR-170 specification. + ModeShape supports all of the built-in node types described in the JSR-283 specification. ModeShape also defines some custom node types in the mode namespace, but none of these - node types except for mode:resource are intended to be used by developers integrating with ModeShape and may be changed or removed + node types (other than mode:resource) are intended to be used by developers integrating with ModeShape and may be changed or removed at any time. Custom Node Type Registration - Although the JSR-170 specification does not require support for registration and unregistration of custom types, ModeShape supports this extremely - useful feature. Custom node types can be added at startup, as noted above or at runtime through a ModeShape-specific interface. ModeShape supports defining node - types either through a JSR-283-like template approach or through the use of &CND; (CND) files. - Both type registration mechanisms are supported equally within ModeShape, although the CND approach for defining node types is recommended. + Although the JSR-283 specification does not require support for registration and unregistration of custom types, ModeShape supports this extremely + useful feature. Custom node types can be added at startup, as noted above, at runtime through a ModeShape-specific interface that accepts CND files, or through the JSR-283 + node type template methods. + All three of these node type registration mechanisms are supported equally within ModeShape, although the CND approach for defining node types is recommended. ModeShape also supports defining custom node types to load at startup. This is discussed in more detail in the previous chapter. @@ -390,12 +813,6 @@ final &LoginContext; loginContext = ...; - The JSR-283 specification provides a useful means of programmatically defining JCR node types. ModeShape supports a comparable - node type definition API that implements the functionality from the specification, albeit with interfaces in the org.modeshape.jcr.nodetype package. - The intent is to deprecate these classes and replace their usage with the JSR-283 equivalents when ModeShape fully supports - the JSR-283 final adopted specification in a future release. - - Node types can be defined like so: &Session; session = ... ; @@ -440,7 +857,7 @@ nodeTypeManager.registerNodeType(nodeType,false); This definition could then be registered as part of the repository configuration, using the &JcrConfiguration; class (see the previous chapter). Or, you can also - use a Session to declare the node types in a CDN file, but this also requires ModeShape-specific interfaces and classes: + use a Session to declare the node types in a CND file, but this also requires ModeShape-specific interfaces and classes: String pathToCndFileInClassLoader = ...; &CndNodeTypeSource; nodeTypeSource = new &CndNodeTypeSource;(pathToCndFileInClassLoader); Index: docs/reference/src/main/docbook/en-US/content/jcr/remote_modeshape_jcr.xml new file mode 100644 =================================================================== --- /dev/null (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/jcr/remote_modeshape_jcr.xml (working copy) @@ -0,0 +1,100 @@ + + + +%CustomDTD; +]> + + Deploying the ModeShape JCR Implementation + + Placeholder for the ModeShape REST Server documentation + + + ModeShape JCR Deployment Models + + One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components + require this context to be passed into individual methods, allowing the context to vary with each method invocation. + Other components require the context to be provided before it's used, and will use that context for all its operations + (until it is given a different one). + + + + Understanding JCR Security in ModeShape + + One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components + require this context to be passed into individual methods, allowing the context to vary with each method invocation. + Other components require the context to be provided before it's used, and will use that context for all its operations + (until it is given a different one). + + + + Configuring Security + + One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components + require this context to be passed into individual methods, allowing the context to vary with each method invocation. + Other components require the context to be provided before it's used, and will use that context for all its operations + (until it is given a different one). + + + + Configuring the Repositories + + One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components + require this context to be passed into individual methods, allowing the context to vary with each method invocation. + Other components require the context to be provided before it's used, and will use that context for all its operations + (until it is given a different one). + + + Choosing the Correct Connectors + + One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components + require this context to be passed into individual methods, allowing the context to vary with each method invocation. + Other components require the context to be provided before it's used, and will use that context for all its operations + (until it is given a different one). + + + + + Configuring ModeShape Core + + One of the objects that must be supplied to many ModeShape components is an &ExecutionContext;. Some components + require this context to be passed into individual methods, allowing the context to vary with each method invocation. + Other components require the context to be provided before it's used, and will use that context for all its operations + (until it is given a different one). + + + + Smoke Testing the Installation + + One such implementation is the &JaasSecurityContext;, which delegates any authentication or authorization requests to a + Java Authentication and Authorization Service (JAAS) + provider. This is the standard approach for authenticating and authorizing in Java, and is the default mechanism + used by the &JcrEngine;. + + + + Index: docs/reference/src/main/docbook/en-US/content/jcr/web_access.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/jcr/web_access.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/jcr/web_access.xml (working copy) @@ -319,7 +319,7 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/ma modeshape org.modeshape - 1.1 + 2.0 ../.. modeshape-web-jcr-webdav-war @@ -357,32 +357,30 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/ma | + configRepository.xml | + log4j.properties (Optional) + /lib - | + activation-1.1.jar | + aperture-1.1.0.Beta1.jar | + google-collections-1.0.jar | + hamcrest-core-1.1.jar | + jakarta-regexp-1.4.jar - | + jaxb-api-2.1.jar - | + jaxb-impl-2.1.12.jar | + jcip-annotations-1.0.jar - | + jcr-1.0.1.jar + | + jcr-2.0.jar | + joda-time-1.6.jar | + junit-dep-4.4.jar | + lucene-analyzers-3.0.0.jar | + lucene-core-3.0.0.jar | + lucene-regex-3.0.0.jar | + lucene-snowball-3.0.0.jar - | + modeshape-cnd-1.1.jar - | + modeshape-common-1.1.jar - | + modeshape-graph-1.1.jar - | + modeshape-jcr-1.1.jar - | + modeshape-mimetype-detector-aperture-1.1.jar - | + modeshape-repository-1.1.jar - | + modeshape-search-lucene-1.1.jar - | + modeshape-web-jcr-1.1.jar - | + modeshape-web-jcr-webdav-1.1.jar + | + modeshape-cnd-2.0.jar + | + modeshape-common-2.0.jar + | + modeshape-graph-2.0.jar + | + modeshape-jcr-2.0.jar + | + modeshape-jcr-api-2.0.jar + | + modeshape-mimetype-detector-aperture-2.0.jar + | + modeshape-repository-2.0.jar + | + modeshape-search-lucene-2.0.jar + | + modeshape-web-jcr-2.0.jar + | + modeshape-web-jcr-webdav-2.0.jar | + rdf2go.api-4.6.2.jar - | + slf4j-api-1.5.8.jar + | + slf4j-api-1.5.11.jar | + slf4j-log4j12-1.5.8.jar | + stax-api-1.0-2.jar | + webdav-servlet-2.0.jar @@ -807,7 +805,7 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/ma modeshape org.modeshape - 1.1 + 2.0 ../.. modeshape-web-jcr-rest-war @@ -819,7 +817,7 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/ma org.modeshape modeshape-web-jcr-rest - 1.1 + 2.0 @@ -832,7 +830,7 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/ma org.jboss.resteasy resteasy-client - 1.1.GA + 1.2.1.GA @@ -865,7 +863,7 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/ma | + jaxrs-api-1.2.1.GA.jar | + jcip-annotations-1.0.jar | + jcl-over-slf4j-1.5.8.jar - | + jcr-1.0.1.jar + | + jcr-2.0.jar | + jettison-1.1.jar | + joda-time-1.6.jar | + jsr250-api-1.0.jar @@ -874,20 +872,21 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/ma | + lucene-core-3.0.0.jar | + lucene-regex-3.0.0.jar | + lucene-snowball-3.0.0.jar - | + modeshape-cnd-1.1.jar - | + modeshape-common-1.1.jar - | + modeshape-graph-1.1.jar - | + modeshape-jcr-1.1.jar - | + modeshape-repository-1.1.jar - | + modeshape-search-lucene-1.1.jar - | + modeshape-web-jcr-1.1.jar - | + modeshape-web-jcr-rest-1.1.jar + | + modeshape-cnd-2.0.jar + | + modeshape-common-2.0.jar + | + modeshape-graph-2.0.jar + | + modeshape-jcr-2.0.jar + | + modeshape-jcr-api-2.0.jar + | + modeshape-repository-2.0.jar + | + modeshape-search-lucene-2.0.jar + | + modeshape-web-jcr-2.0.jar + | + modeshape-web-jcr-rest-2.0.jar | + resteasy-jaxb-provider-1.2.1.GA.jar | + resteasy-jaxrs-1.2.1.GA.jar | + resteasy-jettison-provider-1.2.1.GA.jar | + scannotation-1.0.2.jar | + sjsxp-1.0.1.jar - | + slf4j-api-1.5.8.jar + | + slf4j-api-1.5.11.jar | + slf4j-log4j12-1.5.8.jar | + slf4j-simple-1.5.8.jar | + stax-api-1.0-2.jar Index: docs/reference/src/main/docbook/en-US/content/preface.xml =================================================================== --- docs/reference/src/main/docbook/en-US/content/preface.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/content/preface.xml (working copy) @@ -31,7 +31,7 @@ Target audience - This reference guide is for developers using ModeShape in their applications that want a better understanding of how + This reference guide is for application developers that want a better understanding of how ModeShape works, how to take advantage of its advanced features, and how to extend the functionality. This document is also very valuable for community developers because it covers the design and implementation of most of the components that make up ModeShape. @@ -41,11 +41,9 @@ If you have any questions or comments, please feel free to use ModeShape's - user mailing list or the + user mailing list or user forums. - We welcome all who want to get involved, so if you do please join the mailing lists, - download the code and get it building, and visit our - JIRA issue management system. + We welcome all who want to get involved. If there's something in particular you're interested in, talk with the community - there may be others interested in the same thing. Index: docs/reference/src/main/docbook/en-US/custom.dtd =================================================================== --- docs/reference/src/main/docbook/en-US/custom.dtd (revision 1911) +++ docs/reference/src/main/docbook/en-US/custom.dtd (working copy) @@ -1,4 +1,4 @@ - + @@ -11,25 +11,37 @@ + - + + + + + - - + + + + + + + + + Getting Started"> Reference Guide"> @@ -40,7 +52,7 @@ String"> File"> -FilenameFilter"> +FilenameFilter"> BufferedReader"> URL"> URI"> @@ -73,19 +85,22 @@ -Repository"> -RepositoryFactory"> -Session"> -Credentials"> -SimpleCredentials"> -LoginException"> -AccessDeniedException"> -QueryManager"> -Query"> -QueryResult"> -NodeIterator"> -RowIterator"> -Node"> +Repository"> +RepositoryFactory"> +Session"> +Credentials"> +SimpleCredentials"> +LoginException"> +AccessDeniedException"> +NodeIterator"> +RowIterator"> +Node"> +QueryManager"> +Query"> +QueryResult"> +Binary"> +LockManager"> +VersionManager"> @@ -175,16 +190,15 @@ RequestProcessor"> StreamSequencer"> StreamSequencerContext"> -Sequencer"> SequencerOutput"> SequencerContext"> -MimeTypeDetector"> MockSequencerOutput"> MockSequencerContext"> +MimeTypeDetector"> Observer"> Observable"> ChangeObserver"> -NetChange"> +NetChange"> NetChangeObserver"> ChangeObservers"> Changes"> @@ -199,6 +213,7 @@ ServiceAdministrator"> SequencingService"> SequencerConfig"> +Sequencer"> SessionFactory"> JndiSessionFactory"> SimpleSessionFactory"> @@ -212,7 +227,7 @@ JcrEngine"> JcrConfiguration"> JcrRepository"> -JcrRepositoryFactory"> +JcrRepositoryFactory"> JcrSession"> JndiRepositoryFactory"> SecurityContextCredentials"> @@ -238,11 +253,12 @@ InfinispanSource"> ImageMetadataSequencer"> ImageMetadata"> +ImageMetadataLexicon"> ImageSequencerI18n"> ApertureMimeTypeDetector"> ModeShapeJcrDeployer"> RepositoryProvider"> -RequestResolver"> +RequestResolver"> JavaMetadataSequencer"> SourceFileRecorder"> Index: docs/reference/src/main/docbook/en-US/master.xml =================================================================== --- docs/reference/src/main/docbook/en-US/master.xml (revision 1911) +++ docs/reference/src/main/docbook/en-US/master.xml (working copy) @@ -75,7 +75,7 @@ as well as the configuration and engine in which all the components run. These are all topics covered in this part of the document. - The ModeShape implementation of the JCR API as well as some other + The ModeShape implementation of the JCR API as well as some other JCR-related components are covered in the next part. @@ -88,7 +88,7 @@ ModeShape JCR - The ModeShape project provides an implementation of the JCR API, which is + The ModeShape project provides an implementation of the JCR 2.0 API, which is built on top of the core libraries discussed earlier. This implementation as well as a number of JCR-related components are described in this part of the document. But before talking about how to use the JCR API with a ModeShape repository, first we need to Index: modeshape-jcr/src/main/java/org/modeshape/jcr/JcrRepository.java =================================================================== --- modeshape-jcr/src/main/java/org/modeshape/jcr/JcrRepository.java (revision 1911) +++ modeshape-jcr/src/main/java/org/modeshape/jcr/JcrRepository.java (working copy) @@ -376,6 +376,11 @@ public class JcrRepository implements Repository { * specification. */ public static final String JCR_SQL2 = Query.JCR_SQL2; + + /** + * The enhanced Query Object Model language defined by the JCR 2.0 specification. + */ + public static final String JCR_JQOM = Query.JCR_JQOM; /** * The full-text search language defined as part of the abstract query model, in Section 6.7.19 of the JCR 2.0 * specification. Index: modeshape-jcr/src/main/java/org/modeshape/jcr/JcrRepositoryFactory.java =================================================================== --- modeshape-jcr/src/main/java/org/modeshape/jcr/JcrRepositoryFactory.java (revision 1911) +++ modeshape-jcr/src/main/java/org/modeshape/jcr/JcrRepositoryFactory.java (working copy) @@ -125,18 +125,22 @@ public class JcrRepositoryFactory implements RepositoryFactory { LOG.debug("Trying to load ModeShape JCR Repository with parameters: " + parameters); if (parameters == null) return null; - String rawUrl = (String)parameters.get(URL); + Object rawUrl = parameters.get(URL); if (rawUrl == null) { LOG.debug("No parameter found with key: " + URL); return null; } - URL url; - try { - url = new URL(rawUrl); - } catch (MalformedURLException mue) { - LOG.debug("Could not parse URL: " + mue.getMessage()); - return null; + URL url = null; + if (rawUrl instanceof URL) { + url = (URL)rawUrl; + } else { + try { + url = new URL(rawUrl.toString()); + } catch (MalformedURLException mue) { + LOG.debug("Could not parse URL: " + mue.getMessage()); + return null; + } } if (url.getPath() == null || url.getPath().trim().length() == 0) {