Author: rhauch Date: 2009-09-03 15:07:26 -0400 (Thu, 03 Sep 2009) New Revision: 1191 Added: trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/jpa/ trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/jpa/JcrRepositoryWithJpaConfigurationTest.java trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/svn/ trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/svn/SvnAndJcrIntegrationTest.java Removed: trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/SvnAndJcrIntegrationTest.java Modified: trunk/dna-jcr/src/main/java/org/jboss/dna/jcr/JcrConfiguration.java trunk/dna-repository/src/main/java/org/jboss/dna/repository/DnaConfiguration.java trunk/dna-repository/src/main/java/org/jboss/dna/repository/RepositoryService.java trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml Log: DNA-512 Add simple example (or integration test) that shows all of the code required to use JCR with a JDBC database Created a new JcrRepositoryWithJpaConfigurationTest in the 'dna-integration-test' project that shows from start to finish how to configure a JBoss DNA JCR repository to use a JDBC database (in this case, HSQLDB). Also updated the Reference Guide to more clearly document how to use custom security mechanisms. Deleted: trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/SvnAndJcrIntegrationTest.java =================================================================== --- trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/SvnAndJcrIntegrationTest.java 2009-09-03 16:11:39 UTC (rev 1190) +++ trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/SvnAndJcrIntegrationTest.java 2009-09-03 19:07:26 UTC (rev 1191) @@ -1,123 +0,0 @@ -/* - * JBoss DNA (http://www.jboss.org/dna) - * See the COPYRIGHT.txt file distributed with this work for information - * regarding copyright ownership. Some portions may be licensed - * to Red Hat, Inc. under one or more contributor license agreements. - * See the AUTHORS.txt file in the distribution for a full listing of - * individual contributors. - * - * JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA - * is licensed to you under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation; either version 2.1 of - * the License, or (at your option) any later version. - * - * JBoss DNA is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with this software; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA - * 02110-1301 USA, or see the FSF site: http://www.fsf.org. - */ -package org.jboss.dna.test.integration; - -import static org.hamcrest.core.Is.is; -import static org.hamcrest.core.IsNull.notNullValue; -import static org.junit.Assert.assertThat; -import javax.jcr.NodeIterator; -import javax.jcr.Session; -import org.jboss.dna.connector.svn.SVNRepositorySource; -import org.jboss.dna.graph.SecurityContext; -import org.jboss.dna.jcr.JcrConfiguration; -import org.jboss.dna.jcr.JcrEngine; -import org.jboss.dna.jcr.SecurityContextCredentials; -import org.jboss.dna.jcr.JcrRepository.Option; -import org.junit.After; -import org.junit.Before; -import org.junit.Test; - -/** - * - */ -public class SvnAndJcrIntegrationTest { - private JcrEngine engine; - private Session session; - - @Before - public void beforeEach() throws Exception { - final String repositoryUrl = "http://anonsvn.jboss.org/repos/dna/"; - final String[] predefinedWorkspaceNames = {repositoryUrl + "trunk", repositoryUrl + "tags", repositoryUrl + "branches"}; - final String svnRepositorySource = "svnRepositorySource"; - final String repositoryName = "svnRepository"; - final JcrConfiguration configuration = new JcrConfiguration(); - configuration.repositorySource(svnRepositorySource) - .usingClass(SVNRepositorySource.class) - .setProperty("password", "") - .setProperty("username", "anonymous") - .setProperty("repositoryRootURL", repositoryUrl) - .setProperty("predefinedWorkspaceNames", predefinedWorkspaceNames) - .setProperty("directoryForDefaultWorkspace", predefinedWorkspaceNames[0]) - .setProperty("creatingWorkspacesAllowed", false); - - configuration.repository(repositoryName).setSource(svnRepositorySource).setOption(Option.READ_DEPTH, "1"); - configuration.save(); - this.engine = configuration.build(); - this.engine.start(); - - this.session = this.engine.getRepository(repositoryName) - .login(new SecurityContextCredentials(new MyCustomSecurityContext())); - - } - - @After - public void afterEach() throws Exception { - if (this.session != null) { - this.session.logout(); - } - if (this.engine != null) { - this.engine.shutdown(); - } - } - - @Test - public void shouldIterateOverChildrenOfRoot() throws Exception { - System.out.println("Getting the root node and it's children ..."); - NodeIterator nodeIterator = this.session.getRootNode().getNodes(); - - while (nodeIterator.hasNext()) { - System.out.println(nodeIterator.nextNode()); - } - assertThat(this.session.getRootNode().getNode("dna-graph"), is(notNullValue())); - } - - protected class MyCustomSecurityContext implements SecurityContext { - /** - * {@inheritDoc} - * - * @see org.jboss.dna.graph.SecurityContext#getUserName() - */ - public String getUserName() { - return "Fred"; - } - - /** - * {@inheritDoc} - * - * @see org.jboss.dna.graph.SecurityContext#hasRole(java.lang.String) - */ - public boolean hasRole( String roleName ) { - return true; - } - - /** - * {@inheritDoc} - * - * @see org.jboss.dna.graph.SecurityContext#logout() - */ - public void logout() { - // do something - } - } -} Added: trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/jpa/JcrRepositoryWithJpaConfigurationTest.java =================================================================== --- trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/jpa/JcrRepositoryWithJpaConfigurationTest.java (rev 0) +++ trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/jpa/JcrRepositoryWithJpaConfigurationTest.java 2009-09-03 19:07:26 UTC (rev 1191) @@ -0,0 +1,219 @@ +/* + * JBoss DNA (http://www.jboss.org/dna) + * See the COPYRIGHT.txt file distributed with this work for information + * regarding copyright ownership. Some portions may be licensed + * to Red Hat, Inc. under one or more contributor license agreements. + * See the AUTHORS.txt file in the distribution for a full listing of + * individual contributors. + * + * JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA + * is licensed to you under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * JBoss DNA is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this software; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA, or see the FSF site: http://www.fsf.org. + */ +package org.jboss.dna.test.integration.jpa; + +import static org.hamcrest.core.Is.is; +import static org.hamcrest.core.IsNull.notNullValue; +import static org.junit.Assert.assertThat; +import java.security.AccessController; +import java.security.PrivilegedActionException; +import java.security.PrivilegedExceptionAction; +import java.util.concurrent.TimeUnit; +import javax.jcr.Credentials; +import javax.jcr.Node; +import javax.jcr.NodeIterator; +import javax.jcr.Repository; +import javax.jcr.RepositoryException; +import javax.jcr.Session; +import org.jboss.dna.graph.SecurityContext; +import org.jboss.dna.jcr.JcrConfiguration; +import org.jboss.dna.jcr.JcrEngine; +import org.jboss.dna.jcr.JcrRepository; +import org.jboss.dna.jcr.SecurityContextCredentials; +import org.junit.Test; + +/** + * + */ +public class JcrRepositoryWithJpaConfigurationTest { + + @Test + public void shouldConfigureWithInMemoryDatabase() throws RepositoryException, PrivilegedActionException { + configureWithInMemoryDatabase(new CustomSecurityContext("bill")); + } + + /** + * Test some very basic functionality with an in-memory database and the supplied security context. + * <p> + * Note that this method is designed to be readable and serve as an example, and therefore there is a certain amount of + * repeated code. + * </p> + * + * @param securityContext the security context, or null if JAAS should be used for authentication + * @throws RepositoryException if there was an error with the repository + * @throws PrivilegedActionException if there was an error executing a privileged action block as the current JAAS subject + */ + protected void configureWithInMemoryDatabase( SecurityContext securityContext ) + throws RepositoryException, PrivilegedActionException { + JcrConfiguration configuration = new JcrConfiguration(); + + // Set up the repository source that this JCR repository will use ... + configuration.repositorySource("MySource") + .setDescription("This is my repository source") + .usingClass("org.jboss.dna.connector.store.jpa.JpaSource") + .loadedFromClasspath() + // The rest of these properties are specific to the JpaSource class. + + // Set up three workspaces that this source will make available, + // but for this example allow clients to create more workspaces ... + .setProperty("predefinedWorkspaceNames", "workspace1", "workspace2", "workspace3") + .setProperty("defaultWorkspaceName", "workspace1") + .setProperty("creatingWorkspacesAllowed", true) + // Now set the required JDBC properties, since we're using the 'Driver' approach ... + .setProperty("dialect", "org.hibernate.dialect.HSQLDialect") + .setProperty("driverClassName", "org.hsqldb.jdbcDriver") + .setProperty("username", "sa") + .setProperty("password", "") + .setProperty("url", "jdbc:hsqldb:.") + // Alternatively, you could instead point the source to a JDBC DataSource in JNDI ... + // .setProperty("dataSourceJndiName","jdbc/TestDB") + + // Set some optional properties ... + .setProperty("maximumConnectionsInPool", 3) + .setProperty("minimumConnectionsInPool", 0) + .setProperty("numberOfConnectionsToAcquireAsNeeded", 1) + .setProperty("maximumSizeOfStatementCache", 100) + .setProperty("maximumConnectionIdleTimeInSeconds", 0) + .setProperty("largeValueSizeInBytes", 150) + .setProperty("compressData", true) + .setProperty("referentialIntegrityEnforced", true) + .setProperty("autoDdl", "create") + .setProperty("showSql", false); + + // Set up the JCR repository ... + configuration.repository("My JCR Repository") + .setDescription("This is the description for my JCR repository (not really accessible through JCR though)") + // Tell it which repository source should be used ... + .setSource("MySource") + // Set the options (all of which have good defaults) ... + .setOption(JcrRepository.Option.PROJECT_NODE_TYPES, false) + // Load up some node types ... + // .addNodeTypes(fileOrUrlOrString) + // Register 0 or more namespaces (we'll do an example one here) ... + .registerNamespace("myns", "http://www.example.com/some/namespace"); + + // Build the JcrEngine from the configuration... + JcrEngine engine = configuration.build(); + try { + // First, start the engine ... + engine.start(); + + // Obtain the JCR Repository ... + final Repository myRepository = engine.getRepository("My JCR Repository"); + + // Create a session to our JCR repository, but do this for each of the following workspaces + // (where 'null' means the default workspace, as defined by our source) ... + String[] workspaceNames = {"workspace2", null}; + + for (final String workspaceName : workspaceNames) { + // Log into the JCR repository ... + Session session = null; + if (securityContext != null) { + // Create a JCR Credentials with our custom security context ... + Credentials credentials = new SecurityContextCredentials(securityContext); + // And then login ... + session = myRepository.login(credentials, workspaceName); + } else { + // We don't have a custom SecurityContext, so we'll rely upon JAAS for our security. + // No need to provide a credentials, so just login with the name of the workspace. + // However, we DO need to do this from within a doPrivilege block. + session = AccessController.doPrivileged(new PrivilegedExceptionAction<Session>() { + public Session run() throws Exception { + return myRepository.login(workspaceName); + } + }); + } + assertThat(session, is(notNullValue())); + + // Now do some not-terribly-interesting stuff ... + try { + // Get the root node ... + Node root = session.getRootNode(); + + // Get the "jcr:system" node ... + Node jcrSystem = root.getNode("jcr:system"); + Node namespaces = jcrSystem.getNode("dna:namespaces"); + assert namespaces != null; + + // Create a few children under the root node, all with the same name (but different SNS indexes) ... + for (int i = 0; i != 10; ++i) { + root.addNode("childA", "nt:unstructured"); + } + + // Iterate over the children of the root ... + int childCount = 0; + for (NodeIterator iter = root.getNodes("child* | nonExistant*"); iter.hasNext();) { + Node child = iter.nextNode(); + assertThat(child.getName(), is("childA")); + ++childCount; + } + assertThat(childCount, is(10)); + + } finally { + // Always log out of the session ... + session.logout(); + } + } + + } catch (PrivilegedActionException e) { + // Something went wrong ... + throw e; + } catch (RepositoryException e) { + // Something went wrong ... + throw e; + } finally { + // Shutdown the engine ... + engine.shutdown(); + + // Wait at most 5 seconds for the shutdown to complete ... + try { + engine.awaitTermination(5, TimeUnit.SECONDS); + } catch (InterruptedException e) { + // We were interrupted, but we don't really care. + // But since we're eating this exception, we MUST reset the Thread's flag ... + Thread.interrupted(); + } + } + } + + protected static class CustomSecurityContext implements SecurityContext { + private final String username; + + public CustomSecurityContext( String username ) { + this.username = username; + } + + public String getUserName() { + return username; + } + + public boolean hasRole( String roleName ) { + return true; + } + + public void logout() { + } + + } +} Property changes on: trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/jpa/JcrRepositoryWithJpaConfigurationTest.java ___________________________________________________________________ Name: svn:keywords + Id Revision Name: svn:eol-style + LF Copied: trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/svn/SvnAndJcrIntegrationTest.java (from rev 1190, trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/SvnAndJcrIntegrationTest.java) =================================================================== --- trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/svn/SvnAndJcrIntegrationTest.java (rev 0) +++ trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/svn/SvnAndJcrIntegrationTest.java 2009-09-03 19:07:26 UTC (rev 1191) @@ -0,0 +1,123 @@ +/* + * JBoss DNA (http://www.jboss.org/dna) + * See the COPYRIGHT.txt file distributed with this work for information + * regarding copyright ownership. Some portions may be licensed + * to Red Hat, Inc. under one or more contributor license agreements. + * See the AUTHORS.txt file in the distribution for a full listing of + * individual contributors. + * + * JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA + * is licensed to you under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * JBoss DNA is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this software; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA, or see the FSF site: http://www.fsf.org. + */ +package org.jboss.dna.test.integration.svn; + +import static org.hamcrest.core.Is.is; +import static org.hamcrest.core.IsNull.notNullValue; +import static org.junit.Assert.assertThat; +import javax.jcr.NodeIterator; +import javax.jcr.Session; +import org.jboss.dna.connector.svn.SVNRepositorySource; +import org.jboss.dna.graph.SecurityContext; +import org.jboss.dna.jcr.JcrConfiguration; +import org.jboss.dna.jcr.JcrEngine; +import org.jboss.dna.jcr.SecurityContextCredentials; +import org.jboss.dna.jcr.JcrRepository.Option; +import org.junit.After; +import org.junit.Before; +import org.junit.Test; + +/** + * + */ +public class SvnAndJcrIntegrationTest { + private JcrEngine engine; + private Session session; + + @Before + public void beforeEach() throws Exception { + final String repositoryUrl = "http://anonsvn.jboss.org/repos/dna/"; + final String[] predefinedWorkspaceNames = {repositoryUrl + "trunk", repositoryUrl + "tags", repositoryUrl + "branches"}; + final String svnRepositorySource = "svnRepositorySource"; + final String repositoryName = "svnRepository"; + final JcrConfiguration configuration = new JcrConfiguration(); + configuration.repositorySource(svnRepositorySource) + .usingClass(SVNRepositorySource.class) + .setProperty("password", "") + .setProperty("username", "anonymous") + .setProperty("repositoryRootURL", repositoryUrl) + .setProperty("predefinedWorkspaceNames", predefinedWorkspaceNames) + .setProperty("directoryForDefaultWorkspace", predefinedWorkspaceNames[0]) + .setProperty("creatingWorkspacesAllowed", false); + + configuration.repository(repositoryName).setSource(svnRepositorySource).setOption(Option.READ_DEPTH, "1"); + configuration.save(); + this.engine = configuration.build(); + this.engine.start(); + + this.session = this.engine.getRepository(repositoryName) + .login(new SecurityContextCredentials(new MyCustomSecurityContext())); + + } + + @After + public void afterEach() throws Exception { + if (this.session != null) { + this.session.logout(); + } + if (this.engine != null) { + this.engine.shutdown(); + } + } + + @Test + public void shouldIterateOverChildrenOfRoot() throws Exception { + System.out.println("Getting the root node and it's children ..."); + NodeIterator nodeIterator = this.session.getRootNode().getNodes(); + + while (nodeIterator.hasNext()) { + System.out.println(nodeIterator.nextNode()); + } + assertThat(this.session.getRootNode().getNode("dna-graph"), is(notNullValue())); + } + + protected class MyCustomSecurityContext implements SecurityContext { + /** + * {@inheritDoc} + * + * @see org.jboss.dna.graph.SecurityContext#getUserName() + */ + public String getUserName() { + return "Fred"; + } + + /** + * {@inheritDoc} + * + * @see org.jboss.dna.graph.SecurityContext#hasRole(java.lang.String) + */ + public boolean hasRole( String roleName ) { + return true; + } + + /** + * {@inheritDoc} + * + * @see org.jboss.dna.graph.SecurityContext#logout() + */ + public void logout() { + // do something + } + } +} Property changes on: trunk/dna-integration-tests/src/test/java/org/jboss/dna/test/integration/svn/SvnAndJcrIntegrationTest.java ___________________________________________________________________ Name: svn:keywords + Id Revision Name: svn:eol-style + LF Modified: trunk/dna-jcr/src/main/java/org/jboss/dna/jcr/JcrConfiguration.java =================================================================== --- trunk/dna-jcr/src/main/java/org/jboss/dna/jcr/JcrConfiguration.java 2009-09-03 16:11:39 UTC (rev 1190) +++ trunk/dna-jcr/src/main/java/org/jboss/dna/jcr/JcrConfiguration.java 2009-09-03 19:07:26 UTC (rev 1191) @@ -79,7 +79,8 @@ * * @param <ReturnType> */ - public interface RepositoryDefinition<ReturnType> extends Returnable<ReturnType>, Removable<ReturnType> { + public interface RepositoryDefinition<ReturnType> + extends Returnable<ReturnType>, Removable<ReturnType>, SetDescription<RepositoryDefinition<ReturnType>> { /** * Specify the name of the repository source that is to be used by this JCR repository. @@ -109,6 +110,61 @@ String value ); /** + * Specify the repository option that is to be set. + * + * @param option the option to be set + * @param value the new value for the option + * @return the interface used to set the value for the property; never null + * @throws IllegalArgumentException if either parameter is null + */ + RepositoryDefinition<ReturnType> setOption( JcrRepository.Option option, + boolean value ); + + /** + * Specify the repository option that is to be set. + * + * @param option the option to be set + * @param value the new value for the option + * @return the interface used to set the value for the property; never null + * @throws IllegalArgumentException if either parameter is null + */ + RepositoryDefinition<ReturnType> setOption( JcrRepository.Option option, + int value ); + + /** + * Specify the repository option that is to be set. + * + * @param option the option to be set + * @param value the new value for the option + * @return the interface used to set the value for the property; never null + * @throws IllegalArgumentException if either parameter is null + */ + RepositoryDefinition<ReturnType> setOption( JcrRepository.Option option, + long value ); + + /** + * Specify the repository option that is to be set. + * + * @param option the option to be set + * @param value the new value for the option + * @return the interface used to set the value for the property; never null + * @throws IllegalArgumentException if either parameter is null + */ + RepositoryDefinition<ReturnType> setOption( JcrRepository.Option option, + float value ); + + /** + * Specify the repository option that is to be set. + * + * @param option the option to be set + * @param value the new value for the option + * @return the interface used to set the value for the property; never null + * @throws IllegalArgumentException if either parameter is null + */ + RepositoryDefinition<ReturnType> setOption( JcrRepository.Option option, + double value ); + + /** * Get the value for the repository option. * * @param option the option @@ -498,6 +554,31 @@ return this; } + public RepositoryDefinition<ReturnType> setOption( Option option, + boolean value ) { + return setOption(option, Boolean.toString(value)); + } + + public RepositoryDefinition<ReturnType> setOption( Option option, + int value ) { + return setOption(option, Integer.toString(value)); + } + + public RepositoryDefinition<ReturnType> setOption( Option option, + long value ) { + return setOption(option, Long.toString(value)); + } + + public RepositoryDefinition<ReturnType> setOption( Option option, + float value ) { + return setOption(option, Float.toString(value)); + } + + public RepositoryDefinition<ReturnType> setOption( Option option, + double value ) { + return setOption(option, Double.toString(value)); + } + public String getOption( Option option ) { CheckArg.isNotNull(option, "option"); return optionValues.get(option); Modified: trunk/dna-repository/src/main/java/org/jboss/dna/repository/DnaConfiguration.java =================================================================== --- trunk/dna-repository/src/main/java/org/jboss/dna/repository/DnaConfiguration.java 2009-09-03 16:11:39 UTC (rev 1190) +++ trunk/dna-repository/src/main/java/org/jboss/dna/repository/DnaConfiguration.java 2009-09-03 19:07:26 UTC (rev 1191) @@ -671,6 +671,18 @@ String value ); /** + * Set the property value to a string. + * + * @param beanPropertyName the name of the JavaBean-style property (e.g., "retryLimit") + * @param value the first string value for the property + * @param additionalValues the additional string values for the property + * @return the next component to continue configuration; never null + */ + ReturnType setProperty( String beanPropertyName, + String value, + String... additionalValues ); + + /** * Set the property value to an object. * * @param beanPropertyName the name of the JavaBean-style property (e.g., "retryLimit") @@ -1104,6 +1116,15 @@ return setProperty(beanPropertyName, (Object)value); } + public ThisType setProperty( String beanPropertyName, + String firstValue, + String... additionalValues ) { + Object[] values = new Object[1 + additionalValues.length]; + values[0] = firstValue; + System.arraycopy(additionalValues, 0, values, 1, additionalValues.length); + return setProperty(beanPropertyName, values); + } + public Property getProperty( String beanPropertyName ) { return properties.get(context.getValueFactories().getNameFactory().create(beanPropertyName)); } Modified: trunk/dna-repository/src/main/java/org/jboss/dna/repository/RepositoryService.java =================================================================== --- trunk/dna-repository/src/main/java/org/jboss/dna/repository/RepositoryService.java 2009-09-03 16:11:39 UTC (rev 1190) +++ trunk/dna-repository/src/main/java/org/jboss/dna/repository/RepositoryService.java 2009-09-03 19:07:26 UTC (rev 1191) @@ -420,6 +420,9 @@ } return false; } catch (Exception e) { + // Log that the property was not found ... + Logger.getLogger(getClass()) + .debug("Unknown property '{0}' on '{1}' class", propertyName, target.getClass().getName()); return false; } } Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2009-09-03 16:11:39 UTC (rev 1190) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2009-09-03 19:07:26 UTC (rev 1191) @@ -65,23 +65,36 @@ <sect1 id="jcr-sessions"> <title>Creating JCR Sessions</title> <para>Once you have obtained a reference to the JCR &Repository;, you can create a JCR session using one of its - <code>login(...)</code> methods. The <ulink url="&JSR170;">JSR-170</ulink> specification provides four login methods. + <code>login(...)</code> methods. The <ulink url="&JSR170;">JSR-170</ulink> specification provides four login methods, but the + behavior of these methods depends on the kind of authentication system your application is using. </para> - <para>The first method allows the implementation to choose its own security context to create a session in the default workspace - for the repository. The JBoss DNA JCR implementation uses the security context from the current &AccessControlContext;. This implies + <sect2 id="jcr-sessions-jaas"> + <title>Using JAAS</title> + <para>The <code>login()</code> method allows the implementation to choose its own security context to create a session in the default workspace + for the repository. The JBoss DNA 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;. Here is one example of how this might work: <programlisting> Subject subject = ...; -&Session; session = (&Session;) Subject.doAsPrivileged(subject, new PrivilegedExceptionAction&lt;&Session;&gt;() { +&Session; session = Subject.doAsPrivileged(subject, new PrivilegedExceptionAction&lt;&Session;&gt;() { public Session run() throws Exception { return repository.login(); } }, AccessController.getContext()); </programlisting> - This approach will yield a session with the same user name and roles as <code>subject</code>. There is a comparable - version of <code>login(...)</code> that allows the workspace to be specified by name. + Another variant of this is to use the AccessControlContext directly, which then operates against the current Subject: <programlisting> +&Session; session = AccessController.doPrivileged( new PrivilegedExceptionAction&lt;&Session;&gt;() { + public Session run() throws Exception { + return repository.login(); + } +}); +</programlisting> + </para> + <para> + Either of these approaches will yield a session with the same user name and roles as <code>subject</code>. The <code>login(String workspaceName)</code> + method is comparable and allows the workspace to be specified by name: + <programlisting> Subject subject = ...; final &String; workspaceName = ...; &Session; session = (&Session;) Subject.doAsPrivileged(subject, new PrivilegedExceptionAction&lt;&Session;&gt;() { @@ -90,16 +103,16 @@ }}, AccessController.getContext()); </programlisting> </para> - <para>It is also possible to supply the &Credentials; directly as part of the login process, although JBoss DNA imposes - some requirements on what types of &Credentials; may be supplied. The simplest way is to provide a &SimpleCredentials; object. - These credentials will be validated against the JAAS realm named "dna-jcr" unless another realm name is provided as an option + <para>The JCR API also allows supplying a JCR &Credentials; object directly as part of the login process, although JBoss DNA 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 "dna-jcr", unless another realm name is provided as an option during the JCR repository configuration. For example: <programlisting> &String; userName = ...; char[] password = ...; &Session; session = repository.login(new &SimpleCredentials;(userName, password)); </programlisting> - The credentials-based <code>login(...)</code> method also supports an optional workspace name. + Similarly, the <code>login(Credentials credentials, String workspaceName)</code> method enables passing the credentials and a workspace name: <programlisting> &String; userName = ...; char[] password = ...; @@ -116,19 +129,47 @@ return loginContext; } }, workspaceName); -</programlisting> - Servlet-based applications may wish to reuse the authentication information from &HttpServletRequest; instead. Please note that +</programlisting> + </para> + </sect2> + <sect2 id="jcr-sessions-custom"> + <title>Using Custom security</title> + <para> + Not all applications can or want to use JAAS for their authentication system, so JBoss DNA provides a way to integrate your own custom + security provider. The first step is to provide a custom implementation of &SecurityContext; that integrates with your application security, allowing + JBoss DNA to discover the authenticated user's name, determine whether the authenticated user has been assigned particular roles + (see the <ulink linkend="dna_jcr_security">JCR Security section</ulink>), and to notify your application security system that the + authenticated session (for JCR) has ended. + </para> + <para> + The next step is to wrap your &SecurityContext; instance within an instance of &SecurityContextCredentials;, and pass it as the Credentials + parameter in one of the two <code>login(...)</code> methods: + <programlisting> +&SecurityContext; securityContext = new CustomSecurityContext(...); +&Session; session = repository.login(new &SecurityContextCredentials;(securityContext)); + </programlisting> + Once the &Session; is obtained, the repository content can be accessed and modified like any other JCR repository. + </para> + <para> + At this time, no roles are required to connect to any workspace, but restrictions on workspace connections will likely be added to JBoss DNA in the near future. + Please see the <ulink linkend="dna_jcr_security">JCR Security section</ulink> for more details on how access is controlled. + </para> + </sect2> + <sect2 id="jcr-sessions-servlet"> + <title>Using HTTP Servlet security</title> + <para> + Servlet-based applications can make use of the servlet's existing authentication mechanism from &HttpServletRequest;. Please note that the example below assumes that the servlet has a security constraint that prevents unauthenticated access. <programlisting> &HttpServletRequest; request = ...; -&ServletSecurityContext; securityContext = new ServletSecurityContext(request); -&Session; session = repository.login(new &SecurityContextCredentials;(securityContext); -</programlisting> - Once the &Session; is obtained, the repository content can be accessed and modified like any other JCR repository. No roles are required to connect - to any workspace at this time. Restrictions on workspace connections will likely be added to JBoss DNA in the near future. The roles from the JAAS - information or the &HttpServletRequest; are used to control read and write access to the repository. Please see the <ulink linkend="dna_jcr_security">JCR Security section</ulink> - for more details on how access is controlled. +&SecurityContext; securityContext = new &ServletSecurityContext;(request); +&Session; session = repository.login(new &SecurityContextCredentials;(securityContext)); +</programlisting> + You'll note that this is just a specialization of the <ulink linkend="jcr-sessions-custom">custom security context</ulink> approach, since + the &ServletSecurityContext; just implements the &SecurityContext; interface and delegates to the &HttpServletRequest;. Feel free to use + this class in your servlet-based applications. </para> + </sect2> </sect1> <sect1> <title>JCR Specification Support</title>