Author: bcarothers Date: 2009-06-07 11:05:15 -0400 (Sun, 07 Jun 2009) New Revision: 988 Added: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/package-info.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/package-info.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/package-info.java Modified: trunk/extensions/dna-web-jcr-rest-war/src/test/java/org/jboss/dna/web/jcr/rest/JcrResourcesTest.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/DnaJcrDeployer.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/JcrResources.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/RepositoryFactory.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/ServletSecurityContext.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/RepositoryEntry.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/RepositoryResources.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/WorkspaceEntry.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/WorkspaceResources.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/DnaJcrRepositoryProvider.java trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/RepositoryProvider.java Log: DNA-318 Provide documentation/examples/tutorial explaining use of RESTful API Bolstered Javadoc in dna-web-jcr-rest subproject as a precursor to putting comparable information into the Getting Started and Reference Guide documents. Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/DnaJcrDeployer.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/DnaJcrDeployer.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/DnaJcrDeployer.java 2009-06-07 15:05:15 UTC (rev 988) @@ -1,23 +1,58 @@ +/* + * 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.web.jcr.rest; + import javax.servlet.ServletContextEvent; import javax.servlet.ServletContextListener; +import org.jboss.dna.web.jcr.rest.spi.RepositoryProvider; +import net.jcip.annotations.NotThreadSafe; - +/** + * Servlet context listener that is responsible for {@link RepositoryFactory#initialize(javax.servlet.ServletContext) initializing} + * the {@link RepositoryFactory repository factory}. + * <p> + * This class is not thread safe, but in practice this does not matter as the servlet container must ensure that only + * a single instance of this exists per web context and that it is only called in a single-threaded manner. + * </p> + * @see RepositoryFactory + */ +@NotThreadSafe public class DnaJcrDeployer implements ServletContextListener { - public static final String DEFAULT_JNDI_NAME = "java:comp/env/org/jboss/dna/Engine"; - - public static final String SYSTEM_PROPERTY_JNDI_NAME = "org.jboss.dna.dnaEngineJndiName"; - - public static final String INIT_PARAMETER_JNDI_NAME = "org.jboss.dna.dnaEngineJndiName"; - + /** + * Alerts the repository factory that the web application is shutting down + * @see RepositoryFactory#shutdown() + * @see RepositoryProvider#shutdown() + */ public void contextDestroyed( ServletContextEvent event ) { RepositoryFactory.shutdown(); } /** - * Mounts a DNA engine + * Initializes the repository factory + * @see RepositoryFactory#initialize(javax.servlet.ServletContext) */ public void contextInitialized( ServletContextEvent event ) { RepositoryFactory.initialize(event.getServletContext()); Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/JcrResources.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/JcrResources.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/JcrResources.java 2009-06-07 15:05:15 UTC (rev 988) @@ -55,6 +55,7 @@ import javax.ws.rs.core.Response.Status; import javax.ws.rs.ext.ExceptionMapper; import javax.ws.rs.ext.Provider; +import net.jcip.annotations.Immutable; import org.codehaus.jettison.json.JSONArray; import org.codehaus.jettison.json.JSONException; import org.codehaus.jettison.json.JSONObject; @@ -108,6 +109,7 @@ * </tr> * </table> */ +@Immutable @Path( "/" ) public class JcrResources { Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/RepositoryFactory.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/RepositoryFactory.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/RepositoryFactory.java 2009-06-07 15:05:15 UTC (rev 988) @@ -1,3 +1,26 @@ +/* + * 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.web.jcr.rest; import java.util.Collection; @@ -5,10 +28,33 @@ import javax.jcr.Session; import javax.servlet.ServletContext; import javax.servlet.http.HttpServletRequest; +import net.jcip.annotations.ThreadSafe; +import org.jboss.dna.common.util.CheckArg; import org.jboss.dna.web.jcr.rest.spi.RepositoryProvider; +/** + * Factory that provides implementations of the {@link RepositoryProvider repository provider SPI} by wrapping a + * {@link RepositoryProvider}. + * <p> + * The repository factory implements a lifecycle for the repository providers. It is first {@link #initialize(ServletContext) + * initialized} by {@link DnaJcrDeployer}, a servlet context listener that must be configured in the DNA JCR REST web + * configuration (web.xml). The repository factory looks in the context for a parameter with the name of {@link #PROVIDER_KEY}. + * This is assumed to be the FQN of the {@link RepositoryProvider repository provider}, which the factory will then instantiate. + * </p> + * <p> + * The repository factory is then able to respond to multiple requests to {@link #getJcrRepositoryNames() list the repository + * names} and {@link #getSession(HttpServletRequest, String, String) return active JCR sessions} until the {@link #shutdown() + * shutdown method} is called. + * </p> + * <p> + * The {@link #shutdown() shutdown method} is a simple proxy to the {@link RepositoryProvider#shutdown()} repository provider's + * shutdown method}. + * </p> + */ +@ThreadSafe public class RepositoryFactory { + /** The FQN of the repository provider class. Currently set to {@value} . */ public static final String PROVIDER_KEY = "org.jboss.dna.web.jcr.rest.REPOSITORY_PROVIDER"; private static RepositoryProvider provider; @@ -17,13 +63,20 @@ } + /** + * Initializes the repository factory. For more details, please see the {@link RepositoryFactory class-level documentation}. + * + * @param context the servlet context; may not be null + * @see RepositoryFactory + */ static void initialize( ServletContext context ) { + CheckArg.isNotNull(context, "context"); String className = context.getInitParameter(PROVIDER_KEY); try { Class<? extends RepositoryProvider> providerClass = Class.forName(className).asSubclass(RepositoryProvider.class); provider = providerClass.newInstance(); - + } catch (Exception ex) { throw new IllegalStateException(ex); } @@ -31,7 +84,9 @@ provider.startup(context); } - public static Session getSession( HttpServletRequest request, String repositoryName, String workspaceName) throws RepositoryException { + public static Session getSession( HttpServletRequest request, + String repositoryName, + String workspaceName ) throws RepositoryException { return provider.getSession(request, repositoryName, workspaceName); } Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/ServletSecurityContext.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/ServletSecurityContext.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/ServletSecurityContext.java 2009-06-07 15:05:15 UTC (rev 988) @@ -1,13 +1,42 @@ +/* + * 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.web.jcr.rest; import javax.servlet.http.HttpServletRequest; +import net.jcip.annotations.ThreadSafe; import org.jboss.dna.common.util.CheckArg; import org.jboss.dna.graph.SecurityContext; /** * Servlet-based {@link SecurityContext security context} that assumes servlet-based authentication and provides authorization * through the {@link HttpServletRequest#isUserInRole(String) servlet role-checking mechanism}. + * <p> + * This security context is really only valid for the life of the {@link HttpServletRequest servlet request} and should + * only be used to support longer-lasting session scopes with great care. * + * </p> */ +@ThreadSafe public class ServletSecurityContext implements SecurityContext { private final String userName; Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/RepositoryEntry.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/RepositoryEntry.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/RepositoryEntry.java 2009-06-07 15:05:15 UTC (rev 988) @@ -1,3 +1,26 @@ +/* + * 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.web.jcr.rest.model; import javax.xml.bind.annotation.XmlElement; Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/RepositoryResources.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/RepositoryResources.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/RepositoryResources.java 2009-06-07 15:05:15 UTC (rev 988) @@ -1,3 +1,26 @@ +/* + * 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.web.jcr.rest.model; import javax.xml.bind.annotation.XmlElement; Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/WorkspaceEntry.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/WorkspaceEntry.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/WorkspaceEntry.java 2009-06-07 15:05:15 UTC (rev 988) @@ -1,3 +1,26 @@ +/* + * 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.web.jcr.rest.model; import javax.xml.bind.annotation.XmlElement; Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/WorkspaceResources.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/WorkspaceResources.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/WorkspaceResources.java 2009-06-07 15:05:15 UTC (rev 988) @@ -1,3 +1,26 @@ +/* + * 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.web.jcr.rest.model; import javax.xml.bind.annotation.XmlElement; Added: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/package-info.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/package-info.java (rev 0) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/package-info.java 2009-06-07 15:05:15 UTC (rev 988) @@ -0,0 +1,28 @@ +/* + * 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. + */ +/** + * Models for the DNA interface to faciliate serving basic information as XML or JSON in the future. + */ +package org.jboss.dna.web.jcr.rest.model; + Property changes on: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model/package-info.java ___________________________________________________________________ Name: svn:keywords + Id Revision Name: svn:eol-style + LF Added: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/package-info.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/package-info.java (rev 0) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/package-info.java 2009-06-07 15:05:15 UTC (rev 988) @@ -0,0 +1,36 @@ +/* + * 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. + */ +/** + * This package contains the core components for the DNA REST server implementation. + * <p> + * The key classes are: + * <ul> + * <li>{@link JcrResources} - the class that handles requests for valid URIs</li> + * <li>{@link JcrApplication} - the JAX-RS application class that indicates that JcrResources should be used to handle URIs</li> + * <li>{@link RepositoryFactory} - the interface to the DNA JCR SPI</li> + * </ul> + * </p> + */ +package org.jboss.dna.web.jcr.rest; + Property changes on: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/package-info.java ___________________________________________________________________ Name: svn:keywords + Id Revision Name: svn:eol-style + LF Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/DnaJcrRepositoryProvider.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/DnaJcrRepositoryProvider.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/DnaJcrRepositoryProvider.java 2009-06-07 15:05:15 UTC (rev 988) @@ -1,3 +1,26 @@ +/* + * 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.web.jcr.rest.spi; import java.io.IOException; @@ -9,6 +32,7 @@ import javax.jcr.Session; import javax.servlet.ServletContext; import javax.servlet.http.HttpServletRequest; +import net.jcip.annotations.ThreadSafe; import org.jboss.dna.jcr.JcrConfiguration; import org.jboss.dna.jcr.JcrEngine; import org.jboss.dna.jcr.SecurityContextCredentials; @@ -17,6 +41,18 @@ import org.jboss.resteasy.spi.UnauthorizedException; import org.xml.sax.SAXException; +/** + * Repository provider backed by the DNA JCR implementation. + * <p> + * The provider instantiates a {@link JcrEngine} that is {@link JcrConfiguration#loadFrom(InputStream) configured from} the file + * in the location specified by the servlet context parameter {@code org.jboss.dna.web.jcr.rest.CONFIG_FILE}. This location must + * be accessible by the classloader for this class. + * </p> + * + * @see RepositoryProvider + * @see Class#getResourceAsStream(String) + */ +@ThreadSafe public class DnaJcrRepositoryProvider implements RepositoryProvider { public static final String CONFIG_FILE = "org.jboss.dna.web.jcr.rest.CONFIG_FILE"; @@ -36,7 +72,7 @@ public void startup( ServletContext context ) { String configFile = context.getInitParameter(CONFIG_FILE); - + try { InputStream configFileInputStream = getClass().getResourceAsStream(configFile); jcrEngine = new JcrConfiguration().loadFrom(configFileInputStream).build(); @@ -62,26 +98,26 @@ * @return an active session with the given workspace in the named repository * @throws RepositoryException if any other error occurs */ - public Session getSession( HttpServletRequest request, - String repositoryName, - String workspaceName ) throws RepositoryException { + public Session getSession( HttpServletRequest request, + String repositoryName, + String workspaceName ) throws RepositoryException { assert request != null; - assert request.getUserPrincipal() != null: "Request must be authorized"; + assert request.getUserPrincipal() != null : "Request must be authorized"; // Sanity check in case assertions are disabled if (request.getUserPrincipal() == null) { throw new UnauthorizedException("Client is not authorized"); } - + Repository repository; - + try { repository = getRepository(repositoryName); - + } catch (RepositoryException re) { throw new NotFoundException(re.getMessage(), re); } - + return repository.login(new SecurityContextCredentials(new ServletSecurityContext(request)), workspaceName); } Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/RepositoryProvider.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/RepositoryProvider.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/RepositoryProvider.java 2009-06-07 15:05:15 UTC (rev 988) @@ -1,3 +1,26 @@ +/* + * 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.web.jcr.rest.spi; import java.util.Set; @@ -7,13 +30,18 @@ import javax.servlet.http.HttpServletRequest; /** - * Interface for any class that provides access to one or more local JCR repositories. Repository providers must provide a public, - * no-argument constructor. + * Interface for any class that provides access to one or more local JCR repositories. + * <p> + * Repository providers must provide a public, no-argument constructor and be thread-safe. + * </p> */ public interface RepositoryProvider { /** * Returns an active session for the given workspace name in the named repository. + * <p> + * JCR implementations that do not support multiple repositories on the same server can ignore the repositoryName parameter. + * </p> * * @param request the servlet request; may not be null or unauthenticated * @param repositoryName the name of the repository in which the session is created @@ -21,27 +49,32 @@ * @return an active session with the given workspace in the named repository * @throws RepositoryException if any other error occurs */ - public Session getSession( HttpServletRequest request, - String repositoryName, - String workspaceName ) throws RepositoryException; - + public Session getSession( HttpServletRequest request, + String repositoryName, + String workspaceName ) throws RepositoryException; + /** * Returns the available repository names + * <p> + * JCR implementations that do not support multiple repositories on the same server should provide a singleton set containing + * some default repository name. + * </p> * - * @return the available repository names; may not be null + * @return the available repository names; may not be null or empty */ Set<String> getJcrRepositoryNames(); /** - * Signals the repository provider that it should initialize itself based on the provided {@link ServletContext servlet context} - * and begin accepting connections. + * Signals the repository provider that it should initialize itself based on the provided {@link ServletContext servlet + * context} and begin accepting connections. * * @param context the servlet context for the REST servlet */ - void startup(ServletContext context); + void startup( ServletContext context ); + /** - * Signals the repository provider that it should complete any pending transactions, shutdown, and release - * any external resource held. + * Signals the repository provider that it should complete any pending transactions, shutdown, and release any external + * resource held. */ void shutdown(); Added: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/package-info.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/package-info.java (rev 0) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/package-info.java 2009-06-07 15:05:15 UTC (rev 988) @@ -0,0 +1,42 @@ +/* + * 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. + */ +/** + * Service provider interface (SPI) for the JCR implementation that backs the DNA JCR REST server. + * <p> + * Service providers must provide a thread-safe implementation of the {@link RepositoryProvider} interface + * which is then bundled in the server WAR. The REST server can be configured to use the provider by specifying + * the fully-qualified name (FQN) of the custom repository provider class in the {@code org.jboss.dna.web.jcr.rest.REPOSITORY_PROVIDER} context parameter + * in the web configuration file (web.xml). + * </p> + * <p> + * Custom repository providers for JCR implementations that do not support hosting multiple repositories in the same server + * can context can ignore the {@code repositoryName} parameter for {@link RepositoryProvider#getSession(javax.servlet.http.HttpServletRequest, String, String)}, + * but must always return a non-empty, non-null set containing some default repository name from {@link RepositoryProvider#getJcrRepositoryNames()}. + * </p> + * + * @see org.jboss.dna.web.jcr.rest.RepositoryFactory + * @see org.jboss.dna.web.jcr.rest.spi.RepositoryProvider + */ +package org.jboss.dna.web.jcr.rest.spi; + Property changes on: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/spi/package-info.java ___________________________________________________________________ Name: svn:keywords + Id Revision Name: svn:eol-style + LF Modified: trunk/extensions/dna-web-jcr-rest-war/src/test/java/org/jboss/dna/web/jcr/rest/JcrResourcesTest.java =================================================================== --- trunk/extensions/dna-web-jcr-rest-war/src/test/java/org/jboss/dna/web/jcr/rest/JcrResourcesTest.java 2009-06-07 00:20:55 UTC (rev 987) +++ trunk/extensions/dna-web-jcr-rest-war/src/test/java/org/jboss/dna/web/jcr/rest/JcrResourcesTest.java 2009-06-07 15:05:15 UTC (rev 988) @@ -42,6 +42,12 @@ import org.junit.Before; import org.junit.Test; +/** + * Test of the DNA JCR REST resource. Note that this test case uses a very low-level API to construct + * requests and deconstruct the responses. Users are encouraged to use a higher-level library to communicate + * with the REST server (e.g., Apache HTTP Commons). + * + */ public class JcrResourcesTest { private static final String SERVER_CONTEXT = "/resources";