001: /*
002: * Copyright 2005-2007 Noelios Consulting.
003: *
004: * The contents of this file are subject to the terms of the Common Development
005: * and Distribution License (the "License"). You may not use this file except in
006: * compliance with the License.
007: *
008: * You can obtain a copy of the license at
009: * http://www.opensource.org/licenses/cddl1.txt See the License for the specific
010: * language governing permissions and limitations under the License.
011: *
012: * When distributing Covered Code, include this CDDL HEADER in each file and
013: * include the License file at http://www.opensource.org/licenses/cddl1.txt If
014: * applicable, add the following below this CDDL HEADER, with the fields
015: * enclosed by brackets "[]" replaced with your own identifying information:
016: * Portions Copyright [yyyy] [name of copyright owner]
017: */
018:
019: package org.restlet.service;
020:
021: import org.restlet.data.Reference;
022: import org.restlet.data.Request;
023: import org.restlet.data.Response;
024: import org.restlet.data.Status;
025: import org.restlet.resource.Representation;
026:
027: /**
028: * Service to handle error statuses. If an exception is thrown within your
029: * application or Restlet code, it will be intercepted by this service if it is
030: * enabled.
031: *
032: * When an exception or an error is caught, the
033: * {@link #getStatus(Throwable, Request, Response)} method is first invoked to
034: * obtain the status that you want to set on the response. If this method isn't
035: * overridden or returns null, the {@link Status#SERVER_ERROR_INTERNAL} constant
036: * will be set by default.
037: *
038: * Also, when the status of a response returned is an error status (see
039: * {@link Status#isError()}, the
040: * {@link #getRepresentation(Status, Request, Response)} method is then invoked
041: * to give your service a chance to override the default error page.
042: *
043: * If you want to customize the default behavior, you need to create a subclass
044: * of StatusService that overrides some or all of the methods mentioned above.
045: * Then, just create a instance of your class and set it on your Component or
046: * Application via the setStatusService() methods.
047: *
048: * @author Jerome Louvel (contact@noelios.com)
049: */
050: public class StatusService {
051: /** Indicates if the service has been enabled. */
052: private boolean enabled;
053:
054: /** The email address to contact in case of error. */
055: private String contactEmail;
056:
057: /** The home URI to propose in case of error. */
058: private Reference homeRef;
059:
060: /** True if an existing entity should be overwritten. */
061: private boolean overwrite;
062:
063: /**
064: * Constructor.
065: *
066: * @param enabled
067: * True if the service has been enabled.
068: */
069: public StatusService(boolean enabled) {
070: this .enabled = enabled;
071: this .contactEmail = null;
072: this .homeRef = null;
073: this .overwrite = false;
074: }
075:
076: /**
077: * Returns the email address to contact in case of error. This is typically
078: * used when creating the status representations.
079: *
080: * @return The email address to contact in case of error.
081: */
082: public String getContactEmail() {
083: return this .contactEmail;
084: }
085:
086: /**
087: * Returns the home URI to propose in case of error.
088: *
089: * @return The home URI to propose in case of error.
090: */
091: public Reference getHomeRef() {
092: return this .homeRef;
093: }
094:
095: /**
096: * Returns a representation for the given status.<br/> In order to
097: * customize the default representation, this method can be overriden. It
098: * returns null by default.
099: *
100: * @param status
101: * The status to represent.
102: * @param request
103: * The request handled.
104: * @param response
105: * The response updated.
106: * @return The representation of the given status.
107: */
108: public Representation getRepresentation(Status status,
109: Request request, Response response) {
110: return null;
111: }
112:
113: /**
114: * Returns a status for a given exception or error. By default it returns an
115: * {@link Status#SERVER_ERROR_INTERNAL} status and logs a severe message.<br/>
116: * In order to customize the default behavior, this method can be overriden.
117: *
118: * @param throwable
119: * The exception or error caught.
120: * @param request
121: * The request handled.
122: * @param response
123: * The response updated.
124: * @return The representation of the given status.
125: */
126: public Status getStatus(Throwable throwable, Request request,
127: Response response) {
128: return null;
129: }
130:
131: /**
132: * Indicates if the service should be enabled.
133: *
134: * @return True if the service should be enabled.
135: */
136: public boolean isEnabled() {
137: return this .enabled;
138: }
139:
140: /**
141: * Indicates if an existing entity should be overwritten. False by default.
142: *
143: * @return True if an existing entity should be overwritten.
144: */
145: public boolean isOverwrite() {
146: return this .overwrite;
147: }
148:
149: /**
150: * Sets the email address to contact in case of error. This is typically
151: * used when creating the status representations.
152: *
153: * @param contactEmail
154: * The email address to contact in case of error.
155: */
156: public void setContactEmail(String contactEmail) {
157: this .contactEmail = contactEmail;
158: }
159:
160: /**
161: * Indicates if the service should be enabled.
162: *
163: * @param enabled
164: * True if the service should be enabled.
165: */
166: public void setEnabled(boolean enabled) {
167: this .enabled = enabled;
168: }
169:
170: /**
171: * Sets the home URI to propose in case of error.
172: *
173: * @param homeRef
174: * The home URI to propose in case of error.
175: */
176: public void setHomeRef(Reference homeRef) {
177: this .homeRef = homeRef;
178: }
179:
180: /**
181: * Indicates if an existing entity should be overwritten.
182: *
183: * @param overwrite
184: * True if an existing entity should be overwritten.
185: */
186: public void setOverwrite(boolean overwrite) {
187: this.overwrite = overwrite;
188: }
189:
190: }
|