From 68f51d84d000f9475a74599ecfcce5af170f331e Mon Sep 17 00:00:00 2001 From: Michael Bolz Date: Wed, 24 Sep 2014 09:17:35 +0200 Subject: [PATCH] [OLINGO-443] Added more JavaDoc --- .../org/apache/olingo/server/api/OData.java | 8 +- .../server/api/ODataApplicationException.java | 65 ++++++++++--- .../olingo/server/api/ODataHttpHandler.java | 21 +++-- .../olingo/server/api/ODataRequest.java | 93 +++++++++++++------ .../olingo/server/api/ODataResponse.java | 43 +++++++-- .../olingo/server/api/ODataServerError.java | 33 +++++-- .../server/api/ODataTranslatedException.java | 14 ++- .../CustomContentTypeSupportProcessor.java | 18 ++-- .../api/processor/DefaultProcessor.java | 8 +- .../processor/EntityCollectionProcessor.java | 9 +- .../server/api/processor/EntityProcessor.java | 9 +- .../api/processor/ExceptionProcessor.java | 9 +- .../api/processor/MetadataProcessor.java | 6 +- .../server/api/processor/Processor.java | 12 +-- .../processor/ServiceDocumentProcessor.java | 7 +- .../api/serializer/ODataSerializer.java | 27 +++++- .../serializer/ODataSerializerException.java | 15 +++ .../serializer/ODataSerializerOptions.java | 12 +++ 18 files changed, 301 insertions(+), 108 deletions(-) diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/OData.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/OData.java index d1c669820..6087d89ed 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/OData.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/OData.java @@ -26,7 +26,7 @@ import org.apache.olingo.server.api.serializer.ODataSerializer; import org.apache.olingo.server.api.serializer.ODataSerializerException; /** - * Root object for serving factory tasks and support loosely coupling of implementation (core) from the api. + * Root object for serving factory tasks and support loose coupling of implementation (core) from the API. * This is not a singleton (static variables) to avoid issues with synchronization, OSGi, hot deployment and so on. * Each thread (request) should keep its own instance. */ @@ -54,7 +54,7 @@ public abstract class OData { /** * Creates a new serializer object for rendering content in the specified format. * Serializers are used in Processor implementations. - * @param format - Any format supported by Olingo (XML, JSON ...) + * @param format - any format supported by Olingo (XML, JSON ...) */ public abstract ODataSerializer createSerializer(ODataFormat format) throws ODataSerializerException; @@ -65,8 +65,8 @@ public abstract class OData { public abstract ODataHttpHandler createHandler(Edm edm); /** - * Creates an metadata object. - * @param edmProvider - A custom or default implementation for creating metadata + * Creates a metadata object. + * @param edmProvider - a custom or default implementation for creating metadata */ public abstract Edm createEdm(EdmProvider edmProvider); diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataApplicationException.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataApplicationException.java index 3fb6b4d46..6dda314ad 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataApplicationException.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataApplicationException.java @@ -21,38 +21,79 @@ package org.apache.olingo.server.api; import java.util.Locale; import org.apache.olingo.commons.api.ODataException; +import org.apache.olingo.commons.api.http.HttpStatusCode; +/** + * Exception thrown by OData service implementations. + * @see ODataException + */ public class ODataApplicationException extends ODataException { private static final long serialVersionUID = 5358683245923127425L; - private int statusCode = 500; + private int statusCode = HttpStatusCode.INTERNAL_SERVER_ERROR.getStatusCode(); private Locale locale; private String oDataErrorCode; - public ODataApplicationException(final String msg, int statusCode, Locale locale) { + /** + * Exception in an OData service implementation. + * @param msg the text of the exception + * @param statusCode the HTTP status code of the error response; the default is 500 - Internal Server Error + * @param locale a {@link Locale} to enable translation of error messages + * @see ODataException + * @see HttpStatusCode + */ + public ODataApplicationException(final String msg, final int statusCode, final Locale locale) { super(msg); this.statusCode = statusCode; this.locale = locale; } - public ODataApplicationException(final String msg, int statusCode, Locale locale, String oDataErrorCode) { - super(msg); - this.statusCode = statusCode; - this.locale = locale; + /** + * Exception in an OData service implementation. + * @param msg the text of the exception + * @param statusCode the HTTP status code of the error response; the default is 500 - Internal Server Error + * @param locale a {@link Locale} to enable translation of error messages + * @param oDataErrorCode the error code of the exception as defined by the OData standard + * @see ODataException + * @see HttpStatusCode + */ + public ODataApplicationException(final String msg, final int statusCode, final Locale locale, + final String oDataErrorCode) { + this(msg, statusCode, locale); this.oDataErrorCode = oDataErrorCode; } - public ODataApplicationException(final String msg, int statusCode, Locale locale, final Throwable cause) { + /** + * Exception in an OData service implementation. + * @param msg the text of the exception + * @param statusCode the HTTP status code of the error response; the default is 500 - Internal Server Error + * @param locale a {@link Locale} to enable translation of error messages + * @param cause the cause of this exception + * @see ODataException + * @see HttpStatusCode + * @see Throwable#getCause() + */ + public ODataApplicationException(final String msg, final int statusCode, final Locale locale, + final Throwable cause) { super(msg, cause); this.statusCode = statusCode; this.locale = locale; } - public ODataApplicationException(final String msg, int statusCode, Locale locale, final Throwable cause, - String oDataErrorCode) { - super(msg, cause); - this.statusCode = statusCode; - this.locale = locale; + /** + * Exception in an OData service implementation. + * @param msg the text of the exception + * @param statusCode the HTTP status code of the error response; the default is 500 - Internal Server Error + * @param locale a {@link Locale} to enable translation of error messages + * @param cause the cause of this exception + * @param oDataErrorCode the error code of the exception as defined by the OData standard + * @see ODataException + * @see HttpStatusCode + * @see Throwable#getCause() + */ + public ODataApplicationException(final String msg, final int statusCode, final Locale locale, final Throwable cause, + final String oDataErrorCode) { + this(msg, statusCode, locale, cause); this.oDataErrorCode = oDataErrorCode; } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataHttpHandler.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataHttpHandler.java index 981292755..ad2e8ab2a 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataHttpHandler.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataHttpHandler.java @@ -24,27 +24,30 @@ import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; /** - * Handels http requests as OData requests. + * Handles HTTP requests as OData requests. */ public interface ODataHttpHandler { /** - * Process an OData request. This includes uri parsing, content negotiation, dispatching the request to a specific - * custom processor implementation for handling data and creating the serialized content for the response object. - * @param request - must be a http OData request - * @param response - http OData response + *

Processes an OData request.

+ *

This includes URI parsing, content negotiation, dispatching the request + * to a specific custom processor implementation for handling data and + * creating the serialized content for the response object.

+ * @param request - must be a HTTP OData request + * @param response - HTTP OData response */ void process(HttpServletRequest request, HttpServletResponse response); /** - * Register additional custom processor implementations for handling OData requests. If a request processing requires - * a processor which is not registered then an not implemented exception will happen. + *

Registers additional custom processor implementations for handling OData requests.

+ *

If request processing requires a processor that is not registered then a + * "not implemented" exception will happen.

*/ void register(Processor processor); /** - * Sets the split parameter which is used for service resolution. Default is 0. - * @param split + * Sets the split parameter which is used for service resolution. + * @param split the number of path segments reserved for service resolution; default is 0 */ void setSplit(int split); diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataRequest.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataRequest.java index bba70e2b6..03e293691 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataRequest.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataRequest.java @@ -27,7 +27,7 @@ import java.util.List; import java.util.Map; /** - * Request object carry http information optimized and required to handle OData requests only. + * Request object to carry HTTP information optimized for and required to handle OData requests only. */ public class ODataRequest { private HttpMethod method; @@ -40,21 +40,28 @@ public class ODataRequest { private String rawServiceResolutionUri; /** - * @return the http method (GET, PUT, POST ...) + * Gets the HTTP method. + * @return the HTTP method (GET, PUT, POST ...) */ public HttpMethod getMethod() { return method; } + /** + * Sets the HTTP method. + * @param method the HTTP method (GET, PUT, POST ...) + */ public void setMethod(final HttpMethod method) { this.method = method; } /** - * Add header to request where name handled as case insensitive key. If a header already exists then the list of - * values will just be extended. - * @param name case insensitive header name - * @param values + *

Adds a header to the request.

+ *

The header name will be handled as case-insensitive key.

+ *

If a header already exists then the list of values will just be extended.

+ * @param name case-insensitive header name + * @param values list of values for the given header name + * @see RFC 7230, section 3.2.2 */ public void addHeader(final String name, final List values) { String key = name.toUpperCase(); @@ -72,85 +79,117 @@ public class ODataRequest { } /** - * Returns header value for name where name is a case insensitive key. - * @return the header value or null if not found + * Gets header value for a given name. + * @param name the header name as a case-insensitive key + * @return the header value(s) or null if not found */ public List getHeaders(final String name) { return headers.get(name.toUpperCase()); } /** - * Returns first header value for name where name is a case insensitive key. - * @return the header value or null if not found + * Gets first header value for a given name. + * @param name the header name as a case-insensitive key + * @return the first header value or null if not found */ public String getHeader(final String name) { - List values = getHeaders(name); - return values != null ? values.get(0) : null; + final List values = getHeaders(name); + return values == null ? null : values.get(0); } /** - * @return the request payload or null + * Gets the body of the request. + * @return the request payload as {@link InputStream} or null */ public InputStream getBody() { return body; } + /** + * Sets the body of the request. + * @param body the request payload as {@link InputStream} + */ public void setBody(final InputStream body) { this.body = body; } /** - * @return decoded query options e.g. "$format=json" + * Gets the query part of the request URI. + * @return the undecoded query options, e.g., "$format=json,$top=10" + * @see RFC 3986, section 3.4 */ public String getRawQueryPath() { return rawQueryPath; } + /** + * Sets the query part of the request URI. + * @see #getRawQueryPath() + */ public void setRawQueryPath(final String rawQueryPath) { this.rawQueryPath = rawQueryPath; } /** - * @return encoded base uri e.g. "http://localhost/my%20service" + * Gets the base URI. + * @return undecoded base URI, e.g., "http://localhost/my%20service" */ public String getRawBaseUri() { return rawBaseUri; } /** - * @return encoded request uri e.g. "http://localhost/my%20service/sys1/Employees?$format=json" + * Sets the base URI. + * @see #getRawBaseUri() + */ + public void setRawBaseUri(final String rawBaseUri) { + this.rawBaseUri = rawBaseUri; + } + + /** + * Gets the total request URI. + * @return undecoded request URI, e.g., "http://localhost/my%20service/sys1/Employees?$format=json" */ public String getRawRequestUri() { return rawRequestUri; } /** - * @return encoded OData path segments e.g. "/Employees" + * Sets the total request URI. + * @see #getRawRequestUri() + */ + public void setRawRequestUri(final String rawRequestUri) { + this.rawRequestUri = rawRequestUri; + } + + /** + * Gets the path segments of the request URI that belong to OData. + * @return undecoded OData path segments, e.g., "/Employees" */ public String getRawODataPath() { return rawODataPath; } - public void setRawRequestUri(final String rawRequestUri) { - this.rawRequestUri = rawRequestUri; - } - + /** + * Sets the path segments of the request URI that belong to OData. + * @see #getRawODataPath() + */ public void setRawODataPath(final String rawODataPath) { this.rawODataPath = rawODataPath; - - } - - public void setRawBaseUri(final String rawBaseUri) { - this.rawBaseUri = rawBaseUri; } /** - * @return a decoded path segment that does not belong to the OData url schema or null e.g. "sys1" + * Gets the URI part responsible for service resolution. + * @return undecoded path segments that do not belong to the OData URL schema or null, e.g., "sys1" */ public String getRawServiceResolutionUri() { return rawServiceResolutionUri; } + /** + * Sets the URI part responsible for service resolution. + * @see #getRawServiceResolutionUri() + */ public void setRawServiceResolutionUri(final String rawServiceResolutionUri) { this.rawServiceResolutionUri = rawServiceResolutionUri; } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataResponse.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataResponse.java index b16f60c73..d701e0ba3 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataResponse.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataResponse.java @@ -26,7 +26,7 @@ import java.util.Map; import org.apache.olingo.commons.api.http.HttpStatusCode; /** - * Response object to carry OData relevant http information (statusCode, content & response headers) + * Response object to carry OData-relevant HTTP information (status code, response headers, and content). */ public class ODataResponse { @@ -34,26 +34,51 @@ public class ODataResponse { private Map headers = new HashMap(); private InputStream content; + /** + * Sets the status code. + * @see HttpStatusCode + */ public void setStatusCode(final int statusCode) { this.statusCode = statusCode; } - public void setHeader(final String name, final String value) { - headers.put(name, value); - } - - public void setContent(final InputStream content) { - this.content = content; - } - + /** + * Gets the status code. + * @see HttpStatusCode + */ public int getStatusCode() { return statusCode; } + /** + * Sets a header. + * @param name the name + * @param value the value + */ + public void setHeader(final String name, final String value) { + headers.put(name, value); + } + + /** + * Gets all headers. + * @return an unmodifiable Map of header names/values + */ public Map getHeaders() { return Collections.unmodifiableMap(headers); } + /** + * Sets the content (body). + * @param content the content as {@link InputStream} + */ + public void setContent(final InputStream content) { + this.content = content; + } + + /** + * Gets the content (body). + * @return the content as {@link InputStream} + */ public InputStream getContent() { return content; } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataServerError.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataServerError.java index 434372a13..8b184b251 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataServerError.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataServerError.java @@ -25,6 +25,9 @@ import java.util.Map; import org.apache.olingo.commons.api.domain.ODataError; import org.apache.olingo.commons.api.domain.ODataErrorDetail; +/** + * Server error. + */ public class ODataServerError extends ODataError { private Exception exception; @@ -32,45 +35,61 @@ public class ODataServerError extends ODataError { private Locale locale; /** + * Gets the locale. * @return the locale for the exception message */ public Locale getLocale() { return locale; } + /** + * Sets the locale. + * @return this for method chaining + */ public ODataServerError setLocale(Locale locale) { this.locale = locale; return this; } /** + * Gets the exception. * @return the exception with its hierarchy */ public Exception getException() { return exception; } + /** + * Sets the exception. + * @return this for method chaining + */ public ODataServerError setException(Exception exception) { this.exception = exception; return this; } /** + * Gets the status code. * @return the status code which this error results in. */ public int getStatusCode() { return statusCode; } + /** + * Sets the status code. + * @param statusCode the status code which this error results in + * @return this for method chaining + */ public ODataServerError setStatusCode(int statusCode) { this.statusCode = statusCode; return this; } /** - * The value for the code name/value pair is a language-independent string. Its value is a service-defined error code. - * This code serves as a sub-status for the HTTP error code specified in the response. MAY be null. - * @param code + * The value for the code name/value pair is a language-independent string. + * Its value is a service-defined error code. This code serves as a sub-status + * for the HTTP error code specified in the response. MAY be null. * @return this for method chaining */ public ODataServerError setCode(String code) { @@ -79,9 +98,8 @@ public class ODataServerError extends ODataError { } /** - * The value for the message name/value pair MUST be a human-readable, language-dependent representation of the error. - * MUST not be null - * @param message + * The value for the message name/value pair MUST be a human-readable, + * language-dependent representation of the error. MUST not be null. * @return this for method chaining */ public ODataServerError setMessage(String message) { @@ -92,7 +110,6 @@ public class ODataServerError extends ODataError { /** * The value for the target name/value pair is the target of the particular error (for example, the name of the * property in error). MAY be null. - * @param target * @return this for method chaining */ public ODataServerError setTarget(String target) { @@ -102,7 +119,6 @@ public class ODataServerError extends ODataError { /** * Sets error details. - * * @return this for method chaining. */ public ODataServerError setDetails(List details) { @@ -112,7 +128,6 @@ public class ODataServerError extends ODataError { /** * Sets server defined key-value pairs for debug environment only. - * * @return this for method chaining. */ public ODataServerError setInnerError(Map innerError) { diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataTranslatedException.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataTranslatedException.java index dd4e400e6..43364564a 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataTranslatedException.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataTranslatedException.java @@ -40,7 +40,9 @@ public abstract class ODataTranslatedException extends ODataException { protected static final String DEFAULT_SERVER_BUNDLE_NAME = "server-core-exceptions-i18n"; + /** Key for the exception text in the resource bundle. */ public static interface MessageKey { + /** Gets this key. */ public String getKey(); } @@ -70,10 +72,17 @@ public abstract class ODataTranslatedException extends ODataException { return getMessage(); } + /** Gets the message key. */ public MessageKey getMessageKey() { return messageKey; } + /** + * Gets the translated message text for a given locale (or the default locale if not available), + * returning the developer message text if none is found. + * @param locale the preferred {@link Locale} + * @return the error message + */ public ODataErrorMessage getTranslatedMessage(final Locale locale) { if (messageKey == null) { return new ODataErrorMessage(getMessage(), DEFAULT_LOCALE); @@ -125,19 +134,22 @@ public abstract class ODataTranslatedException extends ODataException { } } + /** Error message text and {@link Locale} used for it. */ public class ODataErrorMessage { String message; Locale locale; - public ODataErrorMessage(String message, Locale usedLocale) { + public ODataErrorMessage(final String message, final Locale usedLocale) { this.message = message; this.locale = usedLocale; } + /** Gets the message text. */ public String getMessage() { return message; } + /** Gets the {@link Locale} used for this message. */ public Locale getLocale() { return locale; } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/CustomContentTypeSupportProcessor.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/CustomContentTypeSupportProcessor.java index 0d94a522b..7969bc86e 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/CustomContentTypeSupportProcessor.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/CustomContentTypeSupportProcessor.java @@ -23,21 +23,23 @@ import java.util.List; import org.apache.olingo.commons.api.format.ContentType; /** - * A processor which supports custom content types can implement this interface. The processor can also remove default - * content types if the default serializer of Olingo are not used. By default this interface is not implemented and - * a processor supports content types implemented by Olingos default serializer (e.g. application/xml for metadata and - * application/json for service document). - * Requesting a content type which is not supported results in a http error 406 (Not Acceptable). + * A processor which supports custom content types can implement this interface. + * The processor can also remove default content types if the default serializers + * of Olingo are not used. By default this interface is not implemented and + * a processor supports content types implemented by Olingo's default serializer + * (e.g., application/xml for the metadata and + * application/json for the service document). + * Requesting a content type that is not supported results in an HTTP error + * 406 (Not Acceptable). */ public interface CustomContentTypeSupportProcessor { /** * Returns a list of supported content types. - * @param defaultContentTypes content types supported by Olingos serializer + * @param defaultContentTypes content types supported by Olingo's serializer + * @param processorClass the {@link Processor} of the current request * @return modified list of supported content types - * */ public List modifySupportedContentTypes( List defaultContentTypes, Class processorClass); - } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/DefaultProcessor.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/DefaultProcessor.java index d62eeb8d0..7e8e9fb0a 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/DefaultProcessor.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/DefaultProcessor.java @@ -35,8 +35,12 @@ import org.apache.olingo.server.api.serializer.ODataSerializerException; import org.apache.olingo.server.api.uri.UriInfo; /** - * Processor implementation for handling of metadata and service document. This implementation is registerd in the - * ODataHandler by default. The default can be replaced by re-registering an custom implementation. + *

Processor implementation for handling default cases: + *

  • request for the metadata document
    • + *
  • request for the service document
    • + *
  • error handling

+ *

This implementation is registered in the ODataHandler by default. + * The default can be replaced by re-registering a custom implementation.

*/ public class DefaultProcessor implements MetadataProcessor, ServiceDocumentProcessor, ExceptionProcessor { diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityCollectionProcessor.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityCollectionProcessor.java index 0e58c965e..a3df302b9 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityCollectionProcessor.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityCollectionProcessor.java @@ -24,17 +24,16 @@ import org.apache.olingo.server.api.ODataResponse; import org.apache.olingo.server.api.uri.UriInfo; /** - * Processor interface for handling collections of entities (collections, EntitySets or feeds). + * Processor interface for handling collections of entities (e.g., EntitySets). */ public interface EntityCollectionProcessor extends Processor { /** - * Read entities data from persistency and puts serialized content and status into the response. - * @param request - OData request object containing raw http information. + * Reads entities data from persistency and puts serialized content and status into the response. + * @param request - OData request object containing raw HTTP information * @param response - OData response object for collecting response data - * @param uriInfo - information of a parsed OData uri + * @param uriInfo - information of a parsed OData URI * @param requestedContentType - requested content type after content negotiation */ void readCollection(ODataRequest request, ODataResponse response, UriInfo uriInfo, ContentType requestedContentType); - } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityProcessor.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityProcessor.java index 7e00f2218..a277fa91f 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityProcessor.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityProcessor.java @@ -24,17 +24,16 @@ import org.apache.olingo.server.api.ODataResponse; import org.apache.olingo.server.api.uri.UriInfo; /** - * Processor interface for handling a single entry (e.g. atom entry). + * Processor interface for handling a single Entity. */ public interface EntityProcessor extends Processor { /** - * Read entity data from persistency and puts serialized content and status into the response. - * @param request - OData request object containing raw http information. + * Reads entity data from persistency and puts serialized content and status into the response. + * @param request - OData request object containing raw HTTP information * @param response - OData response object for collecting response data - * @param uriInfo - information of a parsed OData uri + * @param uriInfo - information of a parsed OData URI * @param requestedContentType - requested content type after content negotiation */ void readEntity(ODataRequest request, ODataResponse response, UriInfo uriInfo, ContentType format); - } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ExceptionProcessor.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ExceptionProcessor.java index f4b4f3e0c..967052b25 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ExceptionProcessor.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ExceptionProcessor.java @@ -24,10 +24,17 @@ import org.apache.olingo.server.api.ODataResponse; import org.apache.olingo.server.api.ODataServerError; /** - * Processor which is called if any exception occurs inside the library or another processor + * Processor which is called if any exception occurs inside the library or another processor. */ public interface ExceptionProcessor extends Processor{ + /** + * Processes an exception. + * @param request the request + * @param response the response + * @param serverError the server error + * @param requestedContentType the requested format for the error message + */ public void processException(ODataRequest request, ODataResponse response, ODataServerError serverError, final ContentType requestedContentType); } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/MetadataProcessor.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/MetadataProcessor.java index 331ba72f4..5abfe670f 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/MetadataProcessor.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/MetadataProcessor.java @@ -30,10 +30,10 @@ import org.apache.olingo.server.api.uri.UriInfo; public interface MetadataProcessor extends Processor { /** - * Read data from persistency and puts serialized content and status into the response. - * @param request - OData request object containing raw http information. + * Reads data from persistency and puts serialized content and status into the response. + * @param request - OData request object containing raw HTTP information * @param response - OData response object for collecting response data - * @param uriInfo - information of a parsed OData uri + * @param uriInfo - information of a parsed OData URI * @param requestedContentType - requested content type after content negotiation */ void readMetadata(ODataRequest request, ODataResponse response, UriInfo uriInfo, ContentType requestedContentType) diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/Processor.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/Processor.java index 5d27ec8d0..1d7e1fb2c 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/Processor.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/Processor.java @@ -22,16 +22,16 @@ import org.apache.olingo.commons.api.edm.Edm; import org.apache.olingo.server.api.OData; /** - * Base interface for all processor types. Processors are responsible to read and write data and marshaling content - * within a request - response cycle. + *

Base interface for all processor types.

+ *

Processors are responsible to read and write data and marshalling content + * within a request - response cycle.

*/ public interface Processor { /** - * Initialize processor for each http request - response cycle. - * @param odata - Olingos root object which acts as a factory for various object types - * @param edm - the edm which needs to be created before the OData request handling takes place + * Initializes the processor for each HTTP request - response cycle. + * @param odata - Olingo's root object, acting as a factory for various object types + * @param edm - the EDM which needs to be created before the OData request handling takes place */ void init(OData odata, Edm edm); - } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ServiceDocumentProcessor.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ServiceDocumentProcessor.java index 4deba80e6..784b28844 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ServiceDocumentProcessor.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ServiceDocumentProcessor.java @@ -29,13 +29,12 @@ import org.apache.olingo.server.api.uri.UriInfo; public interface ServiceDocumentProcessor extends Processor { /** - * Read service document information from persistency and puts serialized content and status into the response. - * @param request - OData request object containing raw http information. + * Reads service-document information from persistency and puts serialized content and status into the response. + * @param request - OData request object containing raw HTTP information * @param response - OData response object for collecting response data - * @param uriInfo - information of a parsed OData uri + * @param uriInfo - information of a parsed OData URI * @param requestedContentType - requested content type after content negotiation */ void readServiceDocument(ODataRequest request, ODataResponse response, UriInfo uriInfo, ContentType requestedContentType); - } diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializer.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializer.java index 91542aaff..8d11ee443 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializer.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializer.java @@ -28,25 +28,47 @@ import org.apache.olingo.server.api.ODataServerError; import org.apache.olingo.server.api.uri.queryoption.ExpandOption; import org.apache.olingo.server.api.uri.queryoption.SelectOption; +/** OData serializer */ public interface ODataSerializer { + /** The default character set is UTF-8. */ public static final String DEFAULT_CHARSET = "UTF-8"; + /** + * Writes the service document into an InputStream. + * @param edm the Entity Data Model + * @param serviceRoot the service-root URI of this OData service + */ InputStream serviceDocument(Edm edm, String serviceRoot) throws ODataSerializerException; + /** + * Writes the metadata document into an InputStream. + * @param edm the Entity Data Model + */ InputStream metadataDocument(Edm edm) throws ODataSerializerException; + /** + * Writes entity data into an InputStream. + * @param edmEntitySet the {@link EdmEntitySet} + * @param entity the data of the entity + * @param options options for the serializer + */ InputStream entity(EdmEntitySet edmEntitySet, Entity entity, ODataSerializerOptions options) throws ODataSerializerException; + /** + * Writes entity-set data into an InputStream. + * @param edmEntitySet the {@link EdmEntitySet} + * @param entitySet the data of the entity set + * @param options options for the serializer + */ InputStream entitySet(EdmEntitySet edmEntitySet, EntitySet entitySet, ODataSerializerOptions options) throws ODataSerializerException; /** * Writes an ODataError into an InputStream. * @param error the main error - * @return inputStream containing the OData formatted error - * @throws ODataSerializerException + * @return inputStream containing the OData-formatted error */ InputStream error(ODataServerError error) throws ODataSerializerException; @@ -56,7 +78,6 @@ public interface ODataSerializer { * @param expand the $expand option * @param select the $select option * @return a String with the select list - * @throws ODataSerializerException */ String buildContextURLSelectList(EdmEntitySet edmEntitySet, ExpandOption expand, SelectOption select) throws ODataSerializerException; diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerException.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerException.java index 615ee3de1..809be0744 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerException.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerException.java @@ -20,10 +20,12 @@ package org.apache.olingo.server.api.serializer; import org.apache.olingo.server.api.ODataTranslatedException; +/** Exception thrown by the {@link ODataSerializer}. */ public class ODataSerializerException extends ODataTranslatedException { private static final long serialVersionUID = 5358683245923127425L; + /** Keys for exception texts in the resource bundle. */ public static enum MessageKeys implements MessageKey { NOT_IMPLEMENTED, /** parameter: format */ UNSUPPORTED_FORMAT, @@ -42,11 +44,24 @@ public class ODataSerializerException extends ODataTranslatedException { } } + /** + * Creates serializer exception. + * @param developmentMessage message text as fallback and for debugging purposes + * @param messageKey one of the {@link MessageKeys} for the exception text in the resource bundle + * @param parameters parameters for the exception text + */ public ODataSerializerException(final String developmentMessage, final MessageKey messageKey, final String... parameters) { super(developmentMessage, messageKey, parameters); } + /** + * Creates serializer exception. + * @param developmentMessage message text as fallback and for debugging purposes + * @param cause the cause of this exception + * @param messageKey one of the {@link MessageKeys} for the exception text in the resource bundle + * @param parameters parameters for the exception text + */ public ODataSerializerException(final String developmentMessage, final Throwable cause, final MessageKey messageKey, final String... parameters) { super(developmentMessage, cause, messageKey, parameters); diff --git a/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerOptions.java b/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerOptions.java index 3e2306623..e4ac7672b 100644 --- a/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerOptions.java +++ b/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerOptions.java @@ -23,6 +23,7 @@ import org.apache.olingo.server.api.uri.queryoption.CountOption; import org.apache.olingo.server.api.uri.queryoption.ExpandOption; import org.apache.olingo.server.api.uri.queryoption.SelectOption; +/** Options for the OData serializer. */ public class ODataSerializerOptions { private ContextURL contextURL; @@ -30,28 +31,34 @@ public class ODataSerializerOptions { private ExpandOption expand; private SelectOption select; + /** Gets the {@link ContextURL}. */ public ContextURL getContextURL() { return contextURL; } + /** Gets the $count system query option. */ public CountOption getCount() { return count; } + /** Gets the $expand system query option. */ public ExpandOption getExpand() { return expand; } + /** Gets the $select system query option. */ public SelectOption getSelect() { return select; } private ODataSerializerOptions() {} + /** Initializes the options builder. */ public static Builder with() { return new Builder(); } + /** Builder of OData serializer options. */ public static final class Builder { private ODataSerializerOptions options; @@ -60,26 +67,31 @@ public class ODataSerializerOptions { options = new ODataSerializerOptions(); } + /** Sets the {@link ContextURL}. */ public Builder contextURL(final ContextURL contextURL) { options.contextURL = contextURL; return this; } + /** Sets the $count system query option. */ public Builder count(final CountOption count) { options.count = count; return this; } + /** Sets the $expand system query option. */ public Builder expand(final ExpandOption expand) { options.expand = expand; return this; } + /** Sets the $select system query option. */ public Builder select(final SelectOption select) { options.select = select; return this; } + /** Builds the OData serializer options. */ public ODataSerializerOptions build() { return options; }