You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@olingo.apache.org by mi...@apache.org on 2014/09/24 09:17:49 UTC
git commit: [OLINGO-443] Added more JavaDoc
Repository: olingo-odata4
Updated Branches:
refs/heads/master 5f5060fdc -> 68f51d84d
[OLINGO-443] Added more JavaDoc
Project: http://git-wip-us.apache.org/repos/asf/olingo-odata4/repo
Commit: http://git-wip-us.apache.org/repos/asf/olingo-odata4/commit/68f51d84
Tree: http://git-wip-us.apache.org/repos/asf/olingo-odata4/tree/68f51d84
Diff: http://git-wip-us.apache.org/repos/asf/olingo-odata4/diff/68f51d84
Branch: refs/heads/master
Commit: 68f51d84d000f9475a74599ecfcce5af170f331e
Parents: 5f5060f
Author: Michael Bolz <mi...@sap.com>
Authored: Wed Sep 24 09:17:35 2014 +0200
Committer: Michael Bolz <mi...@sap.com>
Committed: Wed Sep 24 09:17:35 2014 +0200
----------------------------------------------------------------------
.../org/apache/olingo/server/api/OData.java | 8 +-
.../server/api/ODataApplicationException.java | 65 +++++++++++---
.../olingo/server/api/ODataHttpHandler.java | 21 +++--
.../apache/olingo/server/api/ODataRequest.java | 93 ++++++++++++++------
.../apache/olingo/server/api/ODataResponse.java | 43 +++++++--
.../olingo/server/api/ODataServerError.java | 33 +++++--
.../server/api/ODataTranslatedException.java | 14 ++-
.../CustomContentTypeSupportProcessor.java | 18 ++--
.../server/api/processor/DefaultProcessor.java | 8 +-
.../processor/EntityCollectionProcessor.java | 9 +-
.../server/api/processor/EntityProcessor.java | 9 +-
.../api/processor/ExceptionProcessor.java | 9 +-
.../server/api/processor/MetadataProcessor.java | 6 +-
.../olingo/server/api/processor/Processor.java | 12 +--
.../api/processor/ServiceDocumentProcessor.java | 7 +-
.../server/api/serializer/ODataSerializer.java | 27 +++++-
.../serializer/ODataSerializerException.java | 15 ++++
.../api/serializer/ODataSerializerOptions.java | 12 +++
18 files changed, 301 insertions(+), 108 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/OData.java
----------------------------------------------------------------------
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 d1c6698..6087d89 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);
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataApplicationException.java
----------------------------------------------------------------------
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 3fb6b4d..6dda314 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;
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataHttpHandler.java
----------------------------------------------------------------------
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 9812927..ad2e8ab 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
+ * <p>Processes an OData request.</p>
+ * <p>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.</p>
+ * @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.
+ * <p>Registers additional custom processor implementations for handling OData requests.</p>
+ * <p>If request processing requires a processor that is not registered then a
+ * "not implemented" exception will happen.</p>
*/
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);
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataRequest.java
----------------------------------------------------------------------
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 bba70e2..03e2936 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
+ * <p>Adds a header to the request.</p>
+ * <p>The header name will be handled as case-insensitive key.</p>
+ * <p>If a header already exists then the list of values will just be extended.</p>
+ * @param name case-insensitive header name
+ * @param values list of values for the given header name
+ * @see <a href="http://ietf.org/rfc/rfc7230.txt">RFC 7230, section 3.2.2</a>
*/
public void addHeader(final String name, final List<String> 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<String> 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<String> values = getHeaders(name);
- return values != null ? values.get(0) : null;
+ final List<String> 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., "<code>$format=json,$top=10</code>"
+ * @see <a href="http://ietf.org/rfc/rfc3986.txt">RFC 3986, section 3.4</a>
*/
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., "<code>http://localhost/my%20service</code>"
*/
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 String getRawRequestUri() {
- return rawRequestUri;
+ public void setRawBaseUri(final String rawBaseUri) {
+ this.rawBaseUri = rawBaseUri;
}
/**
- * @return encoded OData path segments e.g. "/Employees"
+ * Gets the total request URI.
+ * @return undecoded request URI, e.g., "<code>http://localhost/my%20service/sys1/Employees?$format=json</code>"
*/
- public String getRawODataPath() {
- return rawODataPath;
+ public String getRawRequestUri() {
+ return rawRequestUri;
}
+ /**
+ * Sets the total request URI.
+ * @see #getRawRequestUri()
+ */
public void setRawRequestUri(final String rawRequestUri) {
this.rawRequestUri = rawRequestUri;
}
- public void setRawODataPath(final String rawODataPath) {
- this.rawODataPath = rawODataPath;
-
+ /**
+ * 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 setRawBaseUri(final String rawBaseUri) {
- this.rawBaseUri = rawBaseUri;
+ /**
+ * Sets the path segments of the request URI that belong to OData.
+ * @see #getRawODataPath()
+ */
+ public void setRawODataPath(final String rawODataPath) {
+ this.rawODataPath = rawODataPath;
}
/**
- * @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., "<code>sys1</code>"
*/
public String getRawServiceResolutionUri() {
return rawServiceResolutionUri;
}
+ /**
+ * Sets the URI part responsible for service resolution.
+ * @see #getRawServiceResolutionUri()
+ */
public void setRawServiceResolutionUri(final String rawServiceResolutionUri) {
this.rawServiceResolutionUri = rawServiceResolutionUri;
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataResponse.java
----------------------------------------------------------------------
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 b16f60c..d701e0b 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<String, String> headers = new HashMap<String, String>();
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<String, String> 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;
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataServerError.java
----------------------------------------------------------------------
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 434372a..8b184b2 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<ODataErrorDetail> 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<String, String> innerError) {
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/ODataTranslatedException.java
----------------------------------------------------------------------
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 dd4e400..4336456 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;
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/CustomContentTypeSupportProcessor.java
----------------------------------------------------------------------
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 0d94a52..7969bc8 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., <code>application/xml</code> for the metadata and
+ * </code>application/json</code> 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<ContentType> modifySupportedContentTypes(
List<ContentType> defaultContentTypes, Class<? extends Processor> processorClass);
-
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/DefaultProcessor.java
----------------------------------------------------------------------
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 d62eeb8..7e8e9fb 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.
+ * <p>Processor implementation for handling default cases:
+ * <ul><li>request for the metadata document</li>
+ * <li>request for the service document</li>
+ * <li>error handling</li></ul></p>
+ * <p>This implementation is registered in the ODataHandler by default.
+ * The default can be replaced by re-registering a custom implementation.</p>
*/
public class DefaultProcessor implements MetadataProcessor, ServiceDocumentProcessor, ExceptionProcessor {
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityCollectionProcessor.java
----------------------------------------------------------------------
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 0e58c96..a3df302 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);
-
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/EntityProcessor.java
----------------------------------------------------------------------
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 7e00f22..a277fa9 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);
-
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ExceptionProcessor.java
----------------------------------------------------------------------
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 f4b4f3e..967052b 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);
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/MetadataProcessor.java
----------------------------------------------------------------------
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 331ba72..5abfe67 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)
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/Processor.java
----------------------------------------------------------------------
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 5d27ec8..1d7e1fb 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.
+ * <p>Base interface for all processor types.</p>
+ * <p>Processors are responsible to read and write data and marshalling content
+ * within a request - response cycle.</p>
*/
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);
-
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/processor/ServiceDocumentProcessor.java
----------------------------------------------------------------------
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 4deba80..784b288 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);
-
}
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializer.java
----------------------------------------------------------------------
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 91542aa..8d11ee4 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;
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerException.java
----------------------------------------------------------------------
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 615ee3d..809be07 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);
http://git-wip-us.apache.org/repos/asf/olingo-odata4/blob/68f51d84/lib/server-api/src/main/java/org/apache/olingo/server/api/serializer/ODataSerializerOptions.java
----------------------------------------------------------------------
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 3e23066..e4ac767 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;
}