[dna-commits] DNA SVN: r988 - in trunk/extensions: dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/model and 2 other directories.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Sun Jun 7 11:05:18 EDT 2009
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
+ */
+ at 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>
*/
+ at 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>
+ */
+ at 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>
*/
+ at 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)
+ */
+ at 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";
More information about the dna-commits
mailing list