[OLINGO-659] Add more javadoc

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/AbstractODataObject.java

@@ -21,6 +21,9 @@ package org.apache.olingo.commons.api.data;
 import java.net.URI;
 import java.text.ParseException;
 
+/**
+ * Abstract OData object with basic values (<code>id</code>, <code>baseURI</code>, <code>title</code>).
+ */
 public abstract class AbstractODataObject extends Annotatable {
 
   private URI baseURI;
@@ -28,20 +31,25 @@ public abstract class AbstractODataObject extends Annotatable {
   private String title;
 
   /**
-   * Gets base URI.
+   * Get base URI.
    *
-   * @return base URI.
+   * @return base URI
    */
   public URI getBaseURI() {
     return baseURI;
   }
 
+  /**
+   * Set base URI.
+   *
+   * @param baseURI new base URI
+   */
   public void setBaseURI(final URI baseURI) {
     this.baseURI = baseURI;
   }
 
   /**
-   * Gest ID.
+   * Get ID.
    *
    * @return ID.
    */
@@ -49,14 +57,31 @@ public abstract class AbstractODataObject extends Annotatable {
     return id;
   }
 
+  /**
+   * Set ID.
+   *
+   * @param id new ID value
+   */
   public void setId(final URI id) {
     this.id = id;
   }
 
+  /**
+   * Get tile.
+   *
+   * @return title
+   */
   public String getTitle() {
     return title;
   }
 
+  /**
+   * Set property with given key to given value.
+   *
+   * @param key key of property
+   * @param value new value for property
+   * @throws ParseException if value can not be parsed
+   */
   public void setCommonProperty(final String key, final String value) throws ParseException {
     if ("id".equals(key)) {
       id = URI.create(value);

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Annotatable.java

@@ -33,15 +33,30 @@ public abstract class Annotatable {
 
   private final List<Annotation> annotations = new ArrayList<Annotation>();
 
+  /**
+   * Get Annotations.
+   *
+   * @return annotations
+   */
   public List<Annotation> getAnnotations() {
     return annotations;
   }
 
+  /**
+   * Compare for equality.
+   *
+   * @param obj to compared with
+   * @return <code>true</code> if equal, otherwise <code>false</code>
+   */
   @Override
   public boolean equals(final Object obj) {
     return EqualsBuilder.reflectionEquals(this, obj);
   }
 
+  /**
+   * Create the hash code.
+   * @return hash code for this instance.
+   */
   @Override
   public int hashCode() {
     return HashCodeBuilder.reflectionHashCode(this);

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Annotation.java

@@ -25,10 +25,18 @@ public class Annotation extends Valuable {
 
   private String term;
 
+  /**
+   * Get term for Annotation.
+   * @return term for Annotation.
+   */
   public String getTerm() {
     return term;
   }
 
+  /**
+   * Set term for Annotation.
+   * @param term term for Annotation.
+   */
   public void setTerm(final String term) {
     this.term = term;
   }

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ComplexValue.java

@@ -25,6 +25,11 @@ public class ComplexValue extends Linked {
 
   private final List<Property> value = new ArrayList<Property>();
 
+  /**
+   * Get list of all values for this ComplexValue.
+   *
+   * @return all values for this ComplexValue (can not be null).
+   */
   public List<Property> getValue() {
     return value;
   }

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ContextURL.java

@@ -50,12 +50,7 @@ public final class ContextURL {
 
   private String odataPath;
 
-  public String getODataPath() {
-    return odataPath;
-  }
-
   public enum Suffix {
-
     ENTITY("$entity"), REFERENCE("$ref"),
     DELTA("$delta"), DELTA_DELETED_ENTITY("$deletedEntity"), DELTA_LINK("$link"), DELTA_DELETED_LINK("$deletedLink");
 
@@ -72,130 +67,252 @@ public final class ContextURL {
 
   private ContextURL() {}
 
+  /**
+   * Get the OData path.
+   * @return the OData path
+   */
+  public String getODataPath() {
+    return odataPath;
+  }
+
+  /**
+   * Get the service root.
+   * @return the service root
+   */
   public URI getServiceRoot() {
     return serviceRoot;
   }
 
+  /**
+   * Get the set entity set / singleton / type.
+   * @return the entity set / singleton / type
+   */
   public String getEntitySetOrSingletonOrType() {
     return entitySetOrSingletonOrType;
   }
 
+  /**
+   * Is context result a collection.
+   * @return <code>true</code> for a collection, otherwise <code>false</code>
+   */
   public boolean isCollection() {
     return isCollection;
   }
 
+  /**
+   * Get the derived entity.
+   * @return derived entity
+   */
   public String getDerivedEntity() {
     return derivedEntity;
   }
 
+  /**
+   * Get the select list.
+   * @return the select list
+   */
   public String getSelectList() {
     return selectList;
   }
 
+  /**
+   * Get the set navigation or property path.
+   * @return the set navigation or property path
+   */
   public String getNavOrPropertyPath() {
     return navOrPropertyPath;
   }
 
+  /**
+   * Get the set key path.
+   * @return the set key path
+   */
   public String getKeyPath() {
     return keyPath;
   }
 
+  /**
+   * Get the set suffix.
+   * @return the set suffix
+   */
   public Suffix getSuffix() {
     return suffix;
   }
 
+  /**
+   * Is context result a entity.
+   * @return <code>true</code> for a reference, otherwise <code>false</code>
+   */
   public boolean isEntity() {
     return suffix == Suffix.ENTITY;
   }
 
+  /**
+   * Is context result a reference.
+   * @return <code>true</code> for a reference, otherwise <code>false</code>
+   */
   public boolean isReference() {
     return suffix == Suffix.REFERENCE;
   }
 
+  /**
+   * Is context result a delta result.
+   * @return <code>true</code> for a delta result, otherwise <code>false</code>
+   */
   public boolean isDelta() {
     return suffix == Suffix.DELTA;
   }
 
+  /**
+   * Is context result a delta deleted entity.
+   * @return <code>true</code> for a delta deleted entity, otherwise <code>false</code>
+   */
   public boolean isDeltaDeletedEntity() {
     return suffix == Suffix.DELTA_DELETED_ENTITY;
   }
 
+  /**
+   * Is context result a delta link.
+   * @return <code>true</code> for a delta link, otherwise <code>false</code>
+   */
   public boolean isDeltaLink() {
     return suffix == Suffix.DELTA_LINK;
   }
 
+  /**
+   * Is context result a delta deleted link.
+   * @return <code>true</code> for a delta deleted link, otherwise <code>false</code>
+   */
   public boolean isDeltaDeletedLink() {
     return suffix == Suffix.DELTA_DELETED_LINK;
   }
 
+  /**
+   * Start building a ContextURL instance.
+   * @return builder for building a ContextURL instance
+   */
   public static Builder with() {
     return new Builder();
   }
 
+  /**
+   * Builder for a ContextURL instance.
+   */
   public static final class Builder {
 
     private final ContextURL contextURL = new ContextURL();
 
+    /**
+     * Set the OData path.
+     * @param oDataPath the OData path
+     */
     public Builder oDataPath(String oDataPath) {
       contextURL.odataPath = oDataPath;
       return this;
     }
 
+    /**
+     * Set the service root.
+     * @param serviceRoot the service root
+     */
     public Builder serviceRoot(final URI serviceRoot) {
       contextURL.serviceRoot = serviceRoot;
       return this;
     }
 
+    /**
+     * Set the edm entity set.
+     * @param entitySet the edm entity set
+     */
     public Builder entitySet(final EdmEntitySet entitySet) {
       contextURL.entitySetOrSingletonOrType = entitySet.getName();
       return this;
     }
 
-    public Builder keyPath(final String value) {
-      contextURL.keyPath = value;
+    /**
+     * Set the key path.
+     * @param keyPath the key path
+     */
+    public Builder keyPath(final String keyPath) {
+      contextURL.keyPath = keyPath;
       return this;
     }
 
+    /**
+     * Set the entity set / singleton / type name.
+     * @param entitySetOrSingletonOrType the entity set / singleton / type name
+     */
     public Builder entitySetOrSingletonOrType(final String entitySetOrSingletonOrType) {
       contextURL.entitySetOrSingletonOrType = entitySetOrSingletonOrType;
       return this;
     }
 
+    /**
+     * Set the edm entity type.
+     * @param type the edm entity type
+     */
     public Builder type(final EdmType type) {
       contextURL.entitySetOrSingletonOrType = type.getFullQualifiedName().toString();
       return this;
     }
 
+    /**
+     * Define the result as a collection.
+     */
     public Builder asCollection() {
       contextURL.isCollection = true;
       return this;
     }
 
+    /**
+     * Set the derived edm entity type.
+     * @param derivedType the derived edm entity type
+     */
     public Builder derived(final EdmEntityType derivedType) {
       contextURL.derivedEntity = derivedType.getFullQualifiedName().getFullQualifiedNameAsString();
       return this;
     }
 
+    /**
+     * Set the derived entity name.
+     * @param derivedEntity the derived entity name
+     */
     public Builder derivedEntity(final String derivedEntity) {
       contextURL.derivedEntity = derivedEntity;
       return this;
     }
 
+    /**
+     * Set the navigation or property path.
+     * @param navOrPropertyPath the navigation or property path
+     */
     public Builder navOrPropertyPath(final String navOrPropertyPath) {
       contextURL.navOrPropertyPath = navOrPropertyPath;
       return this;
     }
 
+    /**
+     * Set the select list.
+     * @param selectList the select list
+     */
     public Builder selectList(final String selectList) {
       contextURL.selectList = selectList;
       return this;
     }
 
+    /**
+     * Set the suffix.
+     * @param suffix the suffix
+     */
     public Builder suffix(final Suffix suffix) {
       contextURL.suffix = suffix;
       return this;
     }
 
+    /**
+     * Create the ContextURL instance based on set values.
+     * @return the according ContextURL
+     */
     public ContextURL build() {
       return contextURL;
     }

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/DeletedEntity.java

@@ -20,10 +20,12 @@ package org.apache.olingo.commons.api.data;
 
 import java.net.URI;
 
+/**
+ * A deleted entity contains the reason for deletion and the id.
+ */
 public class DeletedEntity {
 
   public enum Reason {
-
     deleted,
     changed
 
@@ -32,18 +34,34 @@ public class DeletedEntity {
   private URI id;
   private Reason reason;
 
+  /**
+   * Get id.
+   * @return id
+   */
   public URI getId() {
     return id;
   }
 
+  /**
+   * Set id.
+   * @param id id
+   */
   public void setId(final URI id) {
     this.id = id;
   }
 
+  /**
+   * Get reason for deletion.
+   * @return reason for deletion
+   */
   public Reason getReason() {
     return reason;
   }
 
+  /**
+   * Set reason for deletion.
+   * @param reason for deletion
+   */
   public void setReason(final Reason reason) {
     this.reason = reason;
   }

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Delta.java

@@ -21,22 +21,36 @@ package org.apache.olingo.commons.api.data;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * A Delta instance contains all added and deleted links and all deleted entities.
+ */
 public class Delta extends EntityCollection {
 
   private final List<DeletedEntity> deletedEntities = new ArrayList<DeletedEntity>();
   private final List<DeltaLink> addedLinks = new ArrayList<DeltaLink>();
   private final List<DeltaLink> deletedLinks = new ArrayList<DeltaLink>();
 
+  /**
+   * Get list of deleted entities (must not be NULL).
+   * @return list of deleted entities (must not be NULL)
+   */
   public List<DeletedEntity> getDeletedEntities() {
     return deletedEntities;
   }
 
+  /**
+   * Get list of added links (must not be NULL).
+   * @return list of added links (must not be NULL)
+   */
   public List<DeltaLink> getAddedLinks() {
     return addedLinks;
   }
 
+  /**
+   * Get list of deleted links (must not be NULL).
+   * @return list of deleted links (must not be NULL)
+   */
   public List<DeltaLink> getDeletedLinks() {
     return deletedLinks;
   }
-
 }

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/DeltaLink.java

@@ -20,32 +20,59 @@ package org.apache.olingo.commons.api.data;
 
 import java.net.URI;
 
+/**
+ * A delta link.
+ */
 public class DeltaLink extends Annotatable {
 
   private URI source;
   private String relationship;
   private URI target;
 
+  /**
+   * Get source of this link.
+   * @return source of this link
+   */
   public URI getSource() {
     return source;
   }
 
+  /**
+   * Set source of this link.
+   * @param source source of this link
+   */
   public void setSource(final URI source) {
     this.source = source;
   }
 
+  /**
+   * Get relationship of this link.
+   * @return relationship of this link
+   */
   public String getRelationship() {
     return relationship;
   }
 
+  /**
+   * Set relationship of this link.
+   * @param relationship relationship of this link
+   */
   public void setRelationship(final String relationship) {
     this.relationship = relationship;
   }
 
+  /**
+   * Get target of this link.
+   * @return target of this link
+   */
   public URI getTarget() {
     return target;
   }
 
+  /**
+   * Set target of this link.
+   * @param target target of this link
+   */
   public void setTarget(final URI target) {
     this.target = target;
   }

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Entity.java

@@ -22,6 +22,9 @@ import java.net.URI;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Data representation for a single entity.
+ */
 public class Entity extends Linked {
 
   private String eTag;

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/EntityCollection.java

@@ -22,6 +22,9 @@ import java.net.URI;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Data representation for a collection of single entities.
+ */
 public class EntityCollection extends AbstractODataObject {
 
   private Integer count;

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/GeoUtils.java

@@ -22,8 +22,17 @@ import org.apache.olingo.commons.api.Constants;
 import org.apache.olingo.commons.api.edm.EdmPrimitiveTypeKind;
 import org.apache.olingo.commons.api.edm.geo.Geospatial;
 
+/**
+ * Utilities class for Geography data types.
+ */
 public final class GeoUtils {
 
+  /**
+   * Get dimension based on given Geography / Geometry type.
+   *
+   * @param type a geography / geometry type
+   * @return dimension according to given geography / geometry type
+   */
   public static Geospatial.Dimension getDimension(final EdmPrimitiveTypeKind type) {
     Geospatial.Dimension dimension;
 
@@ -46,6 +55,12 @@ public final class GeoUtils {
     return dimension;
   }
 
+  /**
+   * Get type based on given dimension (Geography / Geometry) and element name.
+   *
+   * @param dimension either geography or geometry
+   * @return elementName name of type
+   */
   public static EdmPrimitiveTypeKind getType(final Geospatial.Dimension dimension, final String elementName) {
     EdmPrimitiveTypeKind type = null;
 

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Link.java

@@ -21,6 +21,9 @@ package org.apache.olingo.commons.api.data;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Data representation for a link.
+ */
 public class Link extends Annotatable {
 
   private String title;
@@ -177,7 +180,7 @@ public class Link extends Annotatable {
 
   /**
    * Sets the binding link.
-   * @param bindingLink
+   * @param bindingLink name of binding link
    */
   public void setBindingLink(final String bindingLink) {
     this.bindingLink = bindingLink;
@@ -185,7 +188,7 @@ public class Link extends Annotatable {
 
   /**
    * Sets the binding links. List MUST NOT be <tt>null</tt>.
-   * @param bindingLinks
+   * @param bindingLinks list of binding link names
    */
   public void setBindingLinks(final List<String> bindingLinks) {
     this.bindingLinks = bindingLinks;

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Linked.java

@@ -21,6 +21,9 @@ package org.apache.olingo.commons.api.data;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Data representation for a linked object.
+ */
 public abstract class Linked extends AbstractODataObject {
 
   private final List<Link> associationLinks = new ArrayList<Link>();

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Operation.java

@@ -20,6 +20,9 @@ package org.apache.olingo.commons.api.data;
 
 import java.net.URI;
 
+/**
+ * Data representation for a operation.
+ */
 public class Operation {
 
   private String metadataAnchor;

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Parameter.java

@@ -18,6 +18,9 @@
  */
 package org.apache.olingo.commons.api.data;
 
+/**
+ * Data representation for a parameter.
+ */
 public class Parameter extends Valuable {
 
   private String name;

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Property.java

@@ -18,6 +18,9 @@
  */
 package org.apache.olingo.commons.api.data;
 
+/**
+ * Data representation for a property.
+ */
 public class Property extends Valuable {
 
   private String name;
@@ -34,14 +37,27 @@ public class Property extends Valuable {
     setValue(valueType, value);
   }
 
+  /**
+   * Get name of property.
+   * @return name of property
+   */
   public String getName() {
     return name;
   }
 
+  /**
+   * Set name of property.
+   * @param name name of property
+   */
   public void setName(final String name) {
     this.name = name;
   }
 
+  /**
+   * Check if this property is <code>null</code> (value == null) or the type is <code>"Edm.Null"</code>.
+   * @return <code>true</code> if this property is <code>null</code> (value == null)
+   *          or the type is <code>"Edm.Null"</code>. Otherwise <code>false</code>.
+   */
   @Override
   public boolean isNull() {
     return getValue() == null || "Edm.Null".equals(getType());

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Valuable.java

@@ -26,20 +26,35 @@ import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
 import org.apache.commons.lang3.builder.ToStringStyle;
 import org.apache.olingo.commons.api.edm.geo.Geospatial;
 
+/**
+ * Defines a value with an according type.
+ */
 public abstract class Valuable extends Annotatable {
 
   private ValueType valueType = null;
   private Object value = null;
   private String type;
 
+  /**
+   * Check if according value is <code>null</code>.
+   * @return <code>true</code> if value is <code>null</code>, otherwise <code>false</code>
+   */
   public boolean isNull() {
     return value == null;
   }
 
+  /**
+   * Get string representation of type (can be null if not set).
+   * @return string representation of type (can be null if not set)
+   */
   public String getType() {
     return type;
   }
 
+  /**
+   * Set string representation of type.
+   * @param type string representation of type
+   */
   public void setType(final String type) {
     this.type = type;
   }
@@ -167,11 +182,20 @@ public abstract class Valuable extends Annotatable {
     return value;
   }
 
+  /**
+   * Set value and value type.
+   * @param valueType value type
+   * @param value value
+   */
   public void setValue(final ValueType valueType, final Object value) {
     this.valueType = valueType;
     this.value = value;
   }
 
+  /**
+   * Get value type for this valuable.
+   * @return value type for this valuable
+   */
   public ValueType getValueType() {
     return valueType;
   }

lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ValueType.java

@@ -18,6 +18,9 @@
  */
 package org.apache.olingo.commons.api.data;
 
+/**
+ * Defines the type of a value (see Valuable).
+ */
 public enum ValueType {
   PRIMITIVE, GEOSPATIAL, ENUM, COMPLEX, ENTITY,
   COLLECTION_PRIMITIVE(PRIMITIVE),
@@ -28,14 +31,18 @@ public enum ValueType {
 
   private final ValueType baseType;
 
-  private ValueType() {
+  ValueType() {
     baseType = this;
   }
 
-  private ValueType(final ValueType baseType) {
+  ValueType(final ValueType baseType) {
     this.baseType = baseType;
   }
 
+  /**
+   * Get base type for this value type.
+   * @return base type
+   */
   public ValueType getBaseType() {
     return baseType;
   }