You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by fm...@apache.org on 2008/01/23 11:16:23 UTC
svn commit: r614480 - in
/incubator/sling/trunk/api/src/main/java/org/apache/sling/api: ./ resource/
scripting/ services/ servlets/
Author: fmeschbe
Date: Wed Jan 23 02:16:21 2008
New Revision: 614480
URL: http://svn.apache.org/viewvc?rev=614480&view=rev
Log:
SLING-186 Merge changes in the exception definitions into trunk
Added:
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/SlingIOException.java
- copied unchanged from r614470, incubator/sling/whiteboard/fmeschbe/effective_exceptions/api/src/main/java/org/apache/sling/api/SlingIOException.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/SlingServletException.java
- copied unchanged from r614470, incubator/sling/whiteboard/fmeschbe/effective_exceptions/api/src/main/java/org/apache/sling/api/SlingServletException.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/QuerySyntaxException.java
- copied unchanged from r614470, incubator/sling/whiteboard/fmeschbe/effective_exceptions/api/src/main/java/org/apache/sling/api/resource/QuerySyntaxException.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceNotFoundException.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/ScriptEvaluationException.java
- copied unchanged from r614470, incubator/sling/whiteboard/fmeschbe/effective_exceptions/api/src/main/java/org/apache/sling/api/scripting/ScriptEvaluationException.java
Removed:
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/HttpStatusCodeException.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/ServiceNotAvailableException.java
Modified:
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/SlingException.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/InvalidServiceFilterSyntaxException.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/ServiceLocator.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/ServletResolver.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingAllMethodsServlet.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingSafeMethodsServlet.java
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/SlingException.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/SlingException.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/SlingException.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/SlingException.java Wed Jan 23 02:16:21 2008
@@ -18,13 +18,18 @@
*/
package org.apache.sling.api;
-import javax.servlet.ServletException;
-
/**
- * The <code>SlingException</code> class defines a general exception that may
- * be thrown when unexpected situations occurr while processing requests.
+ * The <code>SlingException</code> is the base exception used throughout the
+ * Sling API. This exception should only be thrown if there is no more specific
+ * exception defined in the Sling API for the cause and if a cause can be
+ * supplied. Otherwise the more specific exception must be used.
+ * <p>
+ * The <code>SlingException</code> is a <code>RuntimeException</code>
+ * because this exception is not intended to be caught by client code. Rather
+ * this exception (and extensions thereof) should be passed through up to the
+ * actual Sling error and exception handling.
*/
-public class SlingException extends ServletException {
+public class SlingException extends RuntimeException {
/**
* Serial Version ID for pre Java2 RMI
@@ -34,17 +39,17 @@
/**
* Constructs a new Sling exception.
*/
- public SlingException() {
+ protected SlingException() {
super();
}
/**
* Constructs a new Sling exception with the given text. The Sling framework
* may use the text to write it to a log.
- *
+ *
* @param text the exception text
*/
- public SlingException(String text) {
+ protected SlingException(String text) {
super(text);
}
@@ -56,7 +61,7 @@
* <li>include the "root cause" exception
* <li>include a description message
* </ul>
- *
+ *
* @param text the exception text
* @param cause the root cause
*/
@@ -73,10 +78,10 @@
* Constructs a new Sling exception when the Servlet needs to throw an
* exception. The exception's message is based on the localized message of
* the underlying exception.
- *
+ *
* @param cause the root cause
*/
- public SlingException(Throwable cause) {
+ protected SlingException(Throwable cause) {
super(cause);
// ensure proper JDK 1.4 exception chaining
Added: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceNotFoundException.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceNotFoundException.java?rev=614480&view=auto
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceNotFoundException.java (added)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceNotFoundException.java Wed Jan 23 02:16:21 2008
@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sling.api.resource;
+
+import javax.servlet.http.HttpServletResponse;
+
+import org.apache.sling.api.SlingException;
+
+/**
+ * An Exception that causes Sling to return a 404 (NOT FOUND) status code. This
+ * exception should not be caught but rather let be handed up the call stack up
+ * to the Sling error and exception handling.
+ * <p>
+ * The advantage of using this exception over the
+ * <code>HttpServletResponse.sendError</code> methods is that the request can
+ * be aborted immediately all the way up in the call stack and that in addition
+ * to the status code and an optional message a <code>Throwable</code> may be
+ * supplied providing more information.
+ */
+public class ResourceNotFoundException extends SlingException {
+
+ private final int statusCode;
+
+ public ResourceNotFoundException(int statusCode, String message) {
+ super(message);
+ this.statusCode = statusCode;
+ }
+
+ public ResourceNotFoundException(int statusCode, String message,
+ Throwable cause) {
+ super(message, cause);
+ this.statusCode = statusCode;
+ }
+
+ public ResourceNotFoundException(String message, Throwable cause) {
+ super(message, cause);
+ this.statusCode = HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
+ }
+
+ public int getStatusCode() {
+ return statusCode;
+ }
+}
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/resource/ResourceResolver.java Wed Jan 23 02:16:21 2008
@@ -23,8 +23,6 @@
import javax.servlet.http.HttpServletRequest;
-import org.apache.sling.api.SlingException;
-
/**
* The <code>ResourceResolver</code> defines the service API which may be used
* to resolve {@link Resource} objects. The resource resolver is available to
@@ -48,9 +46,13 @@
* @param request The http servlet request object used to resolve the
* resource for.
* @return The {@link Resource} for the request.
- * @throws SlingException May be thrown if another error occurrs.
+ * @throws AccessControlException if the user authenticated with the request
+ * does not have enough rights to access the resource to which
+ * the request maps.
+ * @throws SlingException A subclass of this exception is thrown if the
+ * resource to which the request maps cannot be retrieved.
*/
- Resource resolve(HttpServletRequest request) throws SlingException;
+ Resource resolve(HttpServletRequest request);
/**
* Returns a {@link Resource} object for data located at the given path.
@@ -66,17 +68,17 @@
* (current location) and <code>..</code> (parent location),
* which are resolved by this method. If the path is relative,
* that is the first character is not a slash, a
- * <code>ResourceNotFoundException</code> is thrown.
+ * <code>SlingException</code> is thrown.
* @return The <code>Resource</code> object loaded from the path or
* <code>null</code> if the path does not resolve to a resource.
- * @throws java.security.AccessControlException if an item exists at the
- * <code>path</code> but the session of this resource manager
- * has no read access to the item.
+ * @throws AccessControlException if an item exists at the <code>path</code>
+ * but the session of this resource manager has no read access
+ * to the item.
* @throws SlingException If an error occurrs trying to load the resource
* object from the path or if <code>base</code> is
* <code>null</code> and <code>path</code> is relative.
*/
- Resource getResource(String path) throws SlingException;
+ Resource getResource(String path);
/**
* Returns a {@link Resource} object for data located at the given path.
@@ -100,14 +102,14 @@
* this method.
* @return The <code>Resource</code> object loaded from the path or
* <code>null</code> if the path does not resolve to a resource.
- * @throws java.security.AccessControlException if an item exists at the
- * <code>path</code> but the session of this resource manager
- * has no read access to the item.
+ * @throws AccessControlException if an item exists at the <code>path</code>
+ * but the session of this resource manager has no read access
+ * to the item.
* @throws SlingException If an error occurrs trying to load the resource
* object from the path or if <code>base</code> is
* <code>null</code> and <code>path</code> is relative.
*/
- Resource getResource(Resource base, String path) throws SlingException;
+ Resource getResource(Resource base, String path);
/**
* Returns an <code>Iterator</code> of {@link Resource} objects loaded
@@ -120,15 +122,13 @@
* of the given <code>Resource</code>.
*
* @param parent The {@link Resource Resource} whose children are requested.
- * If <code>null</code> the children of this request's Resource
- * are returned.
* @return An <code>Iterator</code> of {@link Resource} objects.
* @throws NullPointerException If <code>parent</code> is
* <code>null</code>.
* @throws SlingException If any error occurs acquiring the child resource
* iterator.
*/
- Iterator<Resource> listChildren(Resource parent) throws SlingException;
+ Iterator<Resource> listChildren(Resource parent);
/**
* Searches for resources using the given query formulated in the given
@@ -145,10 +145,12 @@
* @param language The language in which the query is formulated.
* @return An <code>Iterator</code> of {@link Resource} objects matching
* the query.
+ * @throws QuerySyntaxException If the query is not syntactically correct
+ * according to the query language indicator of if the query
+ * language is not supported.
* @throws SlingException If an error occurrs querying for the resources.
*/
- Iterator<Resource> findResources(String query, String language)
- throws SlingException;
+ Iterator<Resource> findResources(String query, String language);
/**
* Queries the storage using the given query formulated in the given
@@ -168,10 +170,12 @@
* @param language The language in which the query is formulated.
* @return An <code>Iterator</code> of <code>Map</code> instances
* providing access to the query result.
+ * @throws QuerySyntaxException If the query is not syntactically correct
+ * according to the query language indicator of if the query
+ * language is not supported.
* @throws SlingException If an error occurrs querying for the resources.
*/
- Iterator<Map<String, Object>> queryResources(String query, String language)
- throws SlingException;
+ Iterator<Map<String, Object>> queryResources(String query, String language);
/**
* Adapts this resource resolver to another type. A JCR based resource
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java Wed Jan 23 02:16:21 2008
@@ -18,10 +18,6 @@
*/
package org.apache.sling.api.scripting;
-import java.io.IOException;
-
-import javax.servlet.ServletException;
-
import org.apache.sling.api.resource.Resource;
/**
@@ -47,18 +43,15 @@
/**
* Evaluates this script using the bound variables as global variables to
* the script.
- *
+ *
* @param props The {@link SlingBindings} providing the bound variables for
* evaluating the script. Any bound variables must conform to the
* requirements of the {@link SlingBindings} predefined variables
* set.
- * @throws IOException if an input or output error occurrs.
- * @throws ServletException if another error occurrs evaluating the script.
- * The exception should encapsulate the error cause. This
- * exception is also called if the <code>props</code>
- * predefined bindings are not compliant with the definition in
- * the {@link SlingBindings} class.
+ * @throws ScriptEvaluationException If an error occurrs executing the
+ * script or preparing the script execution. The cause of the
+ * evaluation execption is available as the exception cause.
*/
- void eval(SlingBindings props) throws IOException, ServletException;
+ void eval(SlingBindings props);
}
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java Wed Jan 23 02:16:21 2008
@@ -18,12 +18,10 @@
*/
package org.apache.sling.api.scripting;
-import java.io.IOException;
-
-import javax.servlet.ServletException;
-
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.SlingHttpServletResponse;
+import org.apache.sling.api.SlingIOException;
+import org.apache.sling.api.SlingServletException;
import org.apache.sling.api.request.RequestDispatcherOptions;
/**
@@ -55,27 +53,33 @@
/**
* Same as {@link #include(String,RequestDispatcherOptions)}, but using
* empty options.
+ *
+ * @trows SlingIOException Wrapping a <code>IOException</code> thrown
+ * while handling the include.
+ * @throws SlingServletException Wrapping a <code>ServletException</code>
+ * thrown while handling the include.
*/
- void include(String path) throws ServletException, IOException;
+ void include(String path);
/**
* Helper method to include the result of processing the request for the
* given <code>path</code>. This method is intended to be implemented as
* follows:
- *
+ *
* <pre>
* RequestDispatcher dispatcher = getRequest().getRequestDispatcher(path);
* if (dispatcher != null) {
* dispatcher.include(getRequest(), getResponse());
* }
* </pre>
- *
+ *
* @param path The path to the resource to include.
* @param options influence the rendering of the included Resource
- * @throws ServletException Forwarded from including the resource
- * @throws IOException Forwarded from including the resource
+ * @trows SlingIOException Wrapping a <code>IOException</code> thrown
+ * while handling the include.
+ * @throws SlingServletException Wrapping a <code>ServletException</code>
+ * thrown while handling the include.
*/
- void include(String path, RequestDispatcherOptions options)
- throws ServletException, IOException;
+ void include(String path, RequestDispatcherOptions options);
}
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java Wed Jan 23 02:16:21 2008
@@ -16,7 +16,6 @@
*/
package org.apache.sling.api.scripting;
-import org.apache.sling.api.SlingException;
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.resource.ResourceResolver;
@@ -54,10 +53,12 @@
* {@link SlingScript} is to be found.
* @return The {@link SlingScript} or <code>null</code> if no script can
* be found to handle the request.
+ * @throws AccessControlException If the script to which the request
+ * resolves cannot be accessed due to access control
+ * restrictions.
* @throws SlingException If an error occurrs trying to find a script.
*/
- SlingScript resolveScript(SlingHttpServletRequest request)
- throws SlingException;
+ SlingScript resolveScript(SlingHttpServletRequest request);
/**
* Finds the given name to a {@link SlingScript}.
@@ -73,8 +74,9 @@
* @param name The script name. Must not be <code>null</code>.
* @return The {@link SlingScript} to which the name resolved or
* <code>null</code> otherwise.
+ * @throws AccessControlException If the requested script cannot be accessed
+ * due to access control restrictions.
* @throws SlingException If an error occurrs trying to resolve the name.
*/
- SlingScript findScript(ResourceResolver resourceResolver, String name)
- throws SlingException;
+ SlingScript findScript(ResourceResolver resourceResolver, String name);
}
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/InvalidServiceFilterSyntaxException.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/InvalidServiceFilterSyntaxException.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/InvalidServiceFilterSyntaxException.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/InvalidServiceFilterSyntaxException.java Wed Jan 23 02:16:21 2008
@@ -22,13 +22,23 @@
/** Thrown when an invalid service filter is used */
public class InvalidServiceFilterSyntaxException extends SlingException {
- private static final long serialVersionUID = 1L;
- public InvalidServiceFilterSyntaxException(String reason) {
+ private final String filter;
+
+ public InvalidServiceFilterSyntaxException(String filter, String reason) {
super(reason);
+
+ this.filter = filter;
}
- public InvalidServiceFilterSyntaxException(String reason, Throwable cause) {
+ public InvalidServiceFilterSyntaxException(String filter, String reason,
+ Throwable cause) {
super(reason, cause);
+
+ this.filter = filter;
+ }
+
+ public String getFilter() {
+ return filter;
}
}
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/ServiceLocator.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/ServiceLocator.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/ServiceLocator.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/services/ServiceLocator.java Wed Jan 23 02:16:21 2008
@@ -16,7 +16,6 @@
*/
package org.apache.sling.api.services;
-
/**
* Retrieve named services from a Services registry. Sling OSGi, makes extensive
* use of this interface to locate OSGi services. Microsling also uses it, but
@@ -27,27 +26,22 @@
/**
* Lookup a single service
- *
+ *
* @param serviceName The name (interface) of the service.
* @return The service instance, or null if the service is not available.
*/
<ServiceType> ServiceType getService(Class<ServiceType> type);
/**
- * Same as getService, but throws a ServiceNotAvailableException if the
- * requested service is not currently available
- */
- <ServiceType> ServiceType getRequiredService(Class<ServiceType> type)
- throws ServiceNotAvailableException;
-
- /**
* Lookup one or several services
- *
+ *
* @param serviceName The name (interface) of the service.
* @param filter An optional filter (LDAP-like, see OSGi spec)
* @return The services object or null.
+ * @throws InvalidServiceFilterSyntaxException If the <code>filter</code>
+ * string is not a valid OSGi service filter string.
*/
- <ServiceType> ServiceType[] getServices(Class<ServiceType> serviceType, String filter)
- throws InvalidServiceFilterSyntaxException;;
+ <ServiceType> ServiceType[] getServices(Class<ServiceType> serviceType,
+ String filter);
}
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/ServletResolver.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/ServletResolver.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/ServletResolver.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/ServletResolver.java Wed Jan 23 02:16:21 2008
@@ -19,7 +19,6 @@
package org.apache.sling.api.servlets;
import javax.servlet.Servlet;
-import javax.servlet.ServletException;
import org.apache.sling.api.SlingHttpServletRequest;
@@ -33,8 +32,8 @@
* through a <code>RequestDispatcher</code> is handled by the Sling Framework.
* <p>
* The servlet resolver service is available from the
- * {@link org.apache.sling.api.services.ServiceLocator} using the interface class
- * as parameter.
+ * {@link org.apache.sling.api.services.ServiceLocator} using the interface
+ * class as parameter.
*/
public interface ServletResolver {
@@ -46,16 +45,18 @@
* The returned servlet must be assumed to be initialized and ready to run.
* That is, the <code>init</code> nor the <code>destroy</code> methods
* must <em>NOT</em> be called on the returned servlet.
- *
+ *
* @param request The {@link SlingHttpServletRequest} object used to drive
* selection of the servlet.
* @return The servlet whose <code>service</code> method may be called to
* handle the request.
- * @throws ServletException Is thrown if an error occurrs while trying to
- * find an appropriate servlet to handle the request or if no
- * servlet could be resolved to handle the request.
+ * @throws AccessControlException If the script to which the request
+ * resolves cannot be accessed due to access control
+ * restrictions.
+ * @throws SlingException Is thrown if an error occurrs while trying to find
+ * an appropriate servlet to handle the request or if no servlet
+ * could be resolved to handle the request.
*/
- Servlet resolveServlet(SlingHttpServletRequest request)
- throws ServletException;
+ Servlet resolveServlet(SlingHttpServletRequest request);
}
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingAllMethodsServlet.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingAllMethodsServlet.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingAllMethodsServlet.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingAllMethodsServlet.java Wed Jan 23 02:16:21 2008
@@ -29,7 +29,12 @@
* Helper base class for data modifying Servlets used in Sling. This class
* extends the {@link SlingSafeMethodsServlet} by support for the <em>POST</em>,
* <em>PUT</em> and <em>DELETE</em> methods.
- *
+ * <p>
+ * Implementors note: The methods in this class are all declared to throw the
+ * exceptions according to the intentions of the Servlet API rather than
+ * throwing their Sling RuntimeException counter parts. This is done to easy the
+ * integration with traditional servlets.
+ *
* @see SlingSafeMethodsServlet for more information on supporting more HTTP
* methods
*/
@@ -45,18 +50,17 @@
* <p>
* Implementations of this class should overwrite this method with their
* implementation for the HTTP <em>POST</em> method support.
- *
+ *
* @param request The HTTP request
* @param response The HTTP response
* @throws ServletException Not thrown by this implementation.
- * @throws IOException This implementation throws a
- * {@link HttpStatusCodeException} exception with the
- * appropriate status code and message.
+ * @throws IOException If the error status cannot be reported back to the
+ * client.
*/
protected void doPost(SlingHttpServletRequest request,
SlingHttpServletResponse response) throws ServletException,
IOException {
- handleMethodNotImplemented(request);
+ handleMethodNotImplemented(request, response);
}
/**
@@ -69,18 +73,17 @@
* <p>
* Implementations of this class should overwrite this method with their
* implementation for the HTTP <em>PUT</em> method support.
- *
+ *
* @param request The HTTP request
* @param response The HTTP response
* @throws ServletException Not thrown by this implementation.
- * @throws IOException This implementation throws a
- * {@link HttpStatusCodeException} exception with the
- * appropriate status code and message.
+ * @throws IOException If the error status cannot be reported back to the
+ * client.
*/
protected void doPut(SlingHttpServletRequest request,
SlingHttpServletResponse response) throws ServletException,
IOException {
- handleMethodNotImplemented(request);
+ handleMethodNotImplemented(request, response);
}
/**
@@ -93,18 +96,17 @@
* <p>
* Implementations of this class should overwrite this method with their
* implementation for the HTTP <em>DELETE</em> method support.
- *
+ *
* @param request The HTTP request
* @param response The HTTP response
* @throws ServletException Not thrown by this implementation.
- * @throws IOException This implementation throws a
- * {@link HttpStatusCodeException} exception with the
- * appropriate status code and message.
+ * @throws IOException If the error status cannot be reported back to the
+ * client.
*/
protected void doDelete(SlingHttpServletRequest request,
SlingHttpServletResponse response) throws ServletException,
IOException {
- handleMethodNotImplemented(request);
+ handleMethodNotImplemented(request, response);
}
/**
@@ -116,7 +118,7 @@
* <em>POST</em>, <em>PUT</em> and <em>DELETE</em> and returns
* <code>true</code> if any of these methods is requested. Otherwise
* <code>false</code> is just returned.
- *
+ *
* @param request The HTTP request
* @param response The HTTP response
* @return <code>true</code> if the requested method (<code>request.getMethod()</code>)
@@ -162,7 +164,7 @@
* support for the <em>POST</em>, <em>PUT</em> and <em>DELETE</em>
* methods in addition to the methods returned by the base class
* implementation.
- *
+ *
* @param declaredMethods The public and protected methods declared in the
* extension of this class.
* @return A <code>StringBuffer</code> containing the list of HTTP methods
@@ -194,7 +196,7 @@
* <p>
* This method may be used to make sure a method is actually overwritten and
* not just the default implementation.
- *
+ *
* @param method The Method to check
* @param className The name of class assumed to contained the initial
* declaration of the method.
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingSafeMethodsServlet.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingSafeMethodsServlet.java?rev=614480&r1=614479&r2=614480&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingSafeMethodsServlet.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingSafeMethodsServlet.java Wed Jan 23 02:16:21 2008
@@ -31,10 +31,8 @@
import javax.servlet.ServletOutputStream;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
-import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
-import org.apache.sling.api.HttpStatusCodeException;
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.SlingHttpServletResponse;
import org.apache.sling.api.wrappers.SlingHttpServletResponseWrapper;
@@ -48,8 +46,8 @@
* If any of the default HTTP methods is to be implemented just overwrite the
* respective doXXX method. If additional methods should be supported implement
* appropriate doXXX methods and overwrite the
- * {@link #mayService(SlingHttpServletRequest, SlingHttpServletResponse)} method to
- * dispatch to the doXXX methods as appropriate and overwrite the
+ * {@link #mayService(SlingHttpServletRequest, SlingHttpServletResponse)} method
+ * to dispatch to the doXXX methods as appropriate and overwrite the
* {@link #getAllowedRequestMethods(Map)} to add the new method names.
* <p>
* Please note, that this base class is intended for applications where data is
@@ -61,7 +59,12 @@
* which also contains support for the <em>POST</em>, <em>PUT</em> and
* <em>DELETE</em> methods. This latter class should also be overwritten to
* add support for HTTP methods modifying data.
- *
+ * <p>
+ * Implementors note: The methods in this class are all declared to throw the
+ * exceptions according to the intentions of the Servlet API rather than
+ * throwing their Sling RuntimeException counter parts. This is done to easy the
+ * integration with traditional servlets.
+ *
* @see SlingAllMethodsServlet
*/
public class SlingSafeMethodsServlet extends GenericServlet {
@@ -74,7 +77,7 @@
* the output. Implementations of this class may overwrite this method if
* they have a more performing implementation. Otherwise, they may just keep
* this base implementation.
- *
+ *
* @param request The HTTP request
* @param response The HTTP response which only gets the headers set
* @throws ServletException Forwarded from the
@@ -108,18 +111,17 @@
* <p>
* Implementations of this class should overwrite this method with their
* implementation for the HTTP <em>GET</em> method support.
- *
+ *
* @param request The HTTP request
* @param response The HTTP response
* @throws ServletException Not thrown by this implementation.
- * @throws IOException This implementation throws a
- * {@link HttpStatusCodeException} exception with the
- * appropriate status code and message.
+ * @throws IOException If the error status cannot be reported back to the
+ * client.
*/
protected void doGet(SlingHttpServletRequest request,
SlingHttpServletResponse response) throws ServletException,
IOException {
- handleMethodNotImplemented(request);
+ handleMethodNotImplemented(request, response);
}
/**
@@ -134,7 +136,7 @@
* {@link #getAllowedRequestMethods(Map)} method with the methods gathered.
* The returned value is then used as the value of the <code>Allow</code>
* header set.
- *
+ *
* @param request The HTTP request object. Not used.
* @param response The HTTP response object on which the header is set.
* @throws ServletException Not thrown by this implementation.
@@ -154,7 +156,7 @@
* <p>
* Extensions of this class do not generally need to overwrite this method
* as it contains all there is to be done to the <em>TRACE</em> method.
- *
+ *
* @param request The HTTP request whose headers are returned.
* @param response The HTTP response into which the request headers are
* written.
@@ -211,18 +213,17 @@
* {@link #mayService(HttpServletRequest, HttpServletResponse)} method and
* add support for any extension HTTP methods through an additional doXXX
* method.
- *
+ *
* @param request The HTTP request
* @param response The HTTP response
* @throws ServletException Not thrown by this implementation.
- * @throws IOException This implementation throws a
- * {@link HttpStatusCodeException} exception with the
- * appropriate status code and message.
+ * @throws IOException If the error status cannot be reported back to the
+ * client.
*/
protected void doGeneric(SlingHttpServletRequest request,
SlingHttpServletResponse response) throws ServletException,
IOException {
- handleMethodNotImplemented(request);
+ handleMethodNotImplemented(request, response);
}
/**
@@ -239,7 +240,7 @@
* call this base implementation and in case <code>false</code> is
* returned add handling for any other method and of course return whether
* the requested method was known or not.
- *
+ *
* @param request The HTTP request
* @param response The HTTP response
* @return <code>true</code> if the requested method (<code>request.getMethod()</code>)
@@ -277,26 +278,28 @@
* unhandled HTTP request method. In case of HTTP/1.1 a 405 status code
* (Method Not Allowed) is returned, otherwise a 400 status (Bad Request) is
* returned.
- *
+ *
* @param request The HTTP request from which the method and protocol values
* are extracted to build the appropriate message.
- * @throws HttpStatusCodeException Always thrown by this method containing
- * the appropriate status code and message.
+ * @param response The HTTP response to which the error status is sent.
+ * @throws IOException Thrown if the status cannot be sent to the client.
*/
- protected void handleMethodNotImplemented(SlingHttpServletRequest request)
- throws HttpStatusCodeException {
+ protected void handleMethodNotImplemented(SlingHttpServletRequest request,
+ SlingHttpServletResponse response) throws IOException {
String protocol = request.getProtocol();
String msg = "Method " + request.getMethod() + " not supported";
- // for HTTP/1.1 use 405 Method Not Allowed
if (protocol.endsWith("1.1")) {
- throw new HttpStatusCodeException(
- HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
- }
- // otherwise use 400 Bad Request
- throw new HttpStatusCodeException(HttpServletResponse.SC_BAD_REQUEST,
- msg);
+ // for HTTP/1.1 use 405 Method Not Allowed
+ response.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
+
+ } else {
+
+ // otherwise use 400 Bad Request
+ response.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
+
+ }
}
/**
@@ -313,7 +316,7 @@
* Implementations of this class should not generally overwrite this method.
* Rather the {@link #mayService(HttpServletRequest, HttpServletResponse)}
* method should be overwritten to add support for more HTTP methods.
- *
+ *
* @param request The HTTP request
* @param response The HTTP response
* @throws ServletException Forwarded from the
@@ -346,7 +349,7 @@
* method if the request is a HTTP request.
* <p>
* Implementations of this class will not generally overwrite this method.
- *
+ *
* @param req The Servlet request
* @param res The Servlet response
* @throws ServletException If the request is not a HTTP request or
@@ -388,7 +391,7 @@
* the {@link #mayService(HttpServletRequest, HttpServletResponse)} method).
* This base class implementation should always be called to make sure the
* default HTTP methods are included in the list.
- *
+ *
* @param declaredMethods The public and protected methods declared in the
* extension of this class.
* @return A <code>StringBuffer</code> containing the list of HTTP methods
@@ -424,7 +427,7 @@
* {@link #getAllowedRequestMethods(Map)} method. Note, that only extension
* classes of this class are considered to be sure to not account for the
* default implementations of the doXXX methods in this class.
- *
+ *
* @param c The <code>Class</code> to get the declared methods from
* @return The Map of methods considered for support checking.
*/