[OLINGO-443] Added more JavaDoc

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.
+   * Creates a metadata object.
-   * @param edmProvider - A custom or default implementation for creating metadata
+   * @param edmProvider - a custom or default implementation for creating metadata
    */
   public abstract Edm createEdm(EdmProvider edmProvider);
 

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);
+   * Exception in an OData service implementation.
-    this.statusCode = statusCode;
+   * @param msg            the text of the exception
-    this.locale = locale;
+   * @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) {
+   * Exception in an OData service implementation.
-    super(msg, cause);
+   * @param msg            the text of the exception
-    this.statusCode = statusCode;
+   * @param statusCode     the HTTP status code of the error response; the default is 500 - Internal Server Error
-    this.locale = locale;
+   * @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;
   }
 

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
+   * <p>Processes an OData request.</p>
-   * custom processor implementation for handling data and creating the serialized content for the response object.
+   * <p>This includes URI parsing, content negotiation, dispatching the request
-   * @param request - must be a http OData request
+   * to a specific custom processor implementation for handling data and
-   * @param response - http OData response
+   * 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
+   * <p>Registers additional custom processor implementations for handling OData requests.</p>
-   * a processor which is not registered then an not implemented exception will happen.
+   * <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. 
+   * Sets the split parameter which is used for service resolution.
-   * @param split
+   * @param split the number of path segments reserved for service resolution; default is 0
    */
   void setSplit(int split);
 

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
+   * <p>Adds a header to the request.</p>
-   * values will just be extended.
+   * <p>The header name will be handled as case-insensitive key.</p>
-   * @param name case insensitive header name
+   * <p>If a header already exists then the list of values will just be extended.</p>
-   * @param values
+   * @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.
+   * Gets header value for a given name.
-   * @return the header value or null if not found
+   * @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.
+   * Gets first header value for a given name.
-   * @return the header value or null if not found
+   * @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);
+    final List<String> values = getHeaders(name);
-    return values != null ? values.get(0) : null;
+    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 void setRawBaseUri(final String rawBaseUri) {
+    this.rawBaseUri = rawBaseUri;
+  }
+
+  /**
+   * Gets the total request URI.
+   * @return undecoded request URI, e.g., "<code>http://localhost/my%20service/sys1/Employees?$format=json</code>"
    */
   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., "<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;
   }

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);
+   * Gets the status code.
-  }
+   * @see HttpStatusCode
-
+   */
-  public void setContent(final InputStream content) {
-    this.content = content;
-  }
-
   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;
   }

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.
+   * The value for the code name/value pair is a language-independent string.
-   * This code serves as a sub-status for the HTTP error code specified in the response. MAY be null.
+   * Its value is a service-defined error code. This code serves as a sub-status
-   * @param code
+   * 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.
+   * The value for the message name/value pair MUST be a human-readable,
-   * MUST not be null
+   * language-dependent representation of the error. MUST not be null.
-   * @param message
    * @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) {

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;
     }

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
+ * A processor which supports custom content types can implement this interface.
- * content types if the default serializer of Olingo are not used. By default this interface is not implemented and
+ * The processor can also remove default content types if the default serializers
- * a processor supports content types implemented by Olingos default serializer (e.g. application/xml for metadata and
+ * of Olingo are not used. By default this interface is not implemented and
- * application/json for service document).
+ * a processor supports content types implemented by Olingo's default serializer
- * Requesting a content type which is not supported results in a http error 406 (Not Acceptable).
+ * (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);
-
 }

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
+ * <p>Processor implementation for handling default cases:
- * ODataHandler by default. The default can be replaced by re-registering an custom implementation.
+ * <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 {
 

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.
+   * Reads entities data from persistency and puts serialized content and status into the response.
-   *  @param request - OData request object containing raw http information.
+   *  @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);
-
 }

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.
+   * Reads entity data from persistency and puts serialized content and status into the response.
-   *  @param request - OData request object containing raw http information.
+   *  @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);
-  
 }

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);
 }

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.
+   * Reads data from persistency and puts serialized content and status into the response.
-   * @param request - OData request object containing raw http information.
+   * @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)

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
+ * <p>Base interface for all processor types.</p>
- * within a request - response cycle.
+ * <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.
+   * Initializes the processor for each HTTP request - response cycle.
-   * @param odata - Olingos root object which acts as a factory for various object types
+   * @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
+   * @param edm - the EDM which needs to be created before the OData request handling takes place
    */
   void init(OData odata, Edm edm);
-
 }

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.
+   * 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 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);
-
 }

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
+   * @return inputStream containing the OData-formatted error
-   * @throws ODataSerializerException 
    */
   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;

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);

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;
     }