From fdacf06f93b2144440f757931e466bf867c0fdc2 Mon Sep 17 00:00:00 2001 From: Michael Bolz Date: Mon, 7 Sep 2015 15:44:23 +0200 Subject: [PATCH] [OLINGO-659] Add more javadoc --- .../commons/api/data/AbstractODataObject.java | 31 ++++- .../olingo/commons/api/data/Annotatable.java | 15 ++ .../olingo/commons/api/data/Annotation.java | 8 ++ .../olingo/commons/api/data/ComplexValue.java | 5 + .../olingo/commons/api/data/ContextURL.java | 131 +++++++++++++++++- .../commons/api/data/DeletedEntity.java | 20 ++- .../apache/olingo/commons/api/data/Delta.java | 16 ++- .../olingo/commons/api/data/DeltaLink.java | 27 ++++ .../olingo/commons/api/data/Entity.java | 3 + .../commons/api/data/EntityCollection.java | 3 + .../olingo/commons/api/data/GeoUtils.java | 15 ++ .../apache/olingo/commons/api/data/Link.java | 7 +- .../olingo/commons/api/data/Linked.java | 3 + .../olingo/commons/api/data/Operation.java | 3 + .../olingo/commons/api/data/Parameter.java | 3 + .../olingo/commons/api/data/Property.java | 16 +++ .../olingo/commons/api/data/Valuable.java | 24 ++++ .../olingo/commons/api/data/ValueType.java | 11 +- 18 files changed, 325 insertions(+), 16 deletions(-) diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/AbstractODataObject.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/AbstractODataObject.java index 7e89123f9..b2a566360 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/AbstractODataObject.java +++ b/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 (id, baseURI, title). + */ 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); diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Annotatable.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Annotatable.java index d17da992b..e372acad8 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Annotatable.java +++ b/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 annotations = new ArrayList(); + /** + * Get Annotations. + * + * @return annotations + */ public List getAnnotations() { return annotations; } + /** + * Compare for equality. + * + * @param obj to compared with + * @return true if equal, otherwise false + */ @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); diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Annotation.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Annotation.java index 994cc6ab8..759666b19 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Annotation.java +++ b/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; } diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ComplexValue.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ComplexValue.java index ed22b9448..82a21a6f1 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ComplexValue.java +++ b/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 value = new ArrayList(); + /** + * Get list of all values for this ComplexValue. + * + * @return all values for this ComplexValue (can not be null). + */ public List getValue() { return value; } diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ContextURL.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ContextURL.java index 4ff3a0fd8..be0d866b9 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ContextURL.java +++ b/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 true for a collection, otherwise false + */ 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 true for a reference, otherwise false + */ public boolean isEntity() { return suffix == Suffix.ENTITY; } + /** + * Is context result a reference. + * @return true for a reference, otherwise false + */ public boolean isReference() { return suffix == Suffix.REFERENCE; } + /** + * Is context result a delta result. + * @return true for a delta result, otherwise false + */ public boolean isDelta() { return suffix == Suffix.DELTA; } + /** + * Is context result a delta deleted entity. + * @return true for a delta deleted entity, otherwise false + */ public boolean isDeltaDeletedEntity() { return suffix == Suffix.DELTA_DELETED_ENTITY; } + /** + * Is context result a delta link. + * @return true for a delta link, otherwise false + */ public boolean isDeltaLink() { return suffix == Suffix.DELTA_LINK; } + /** + * Is context result a delta deleted link. + * @return true for a delta deleted link, otherwise false + */ 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; } diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/DeletedEntity.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/DeletedEntity.java index a3fe2ccd8..3ae471e6b 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/DeletedEntity.java +++ b/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; } diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Delta.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Delta.java index d825d78f3..1030082ca 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Delta.java +++ b/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 deletedEntities = new ArrayList(); private final List addedLinks = new ArrayList(); private final List deletedLinks = new ArrayList(); + /** + * Get list of deleted entities (must not be NULL). + * @return list of deleted entities (must not be NULL) + */ public List getDeletedEntities() { return deletedEntities; } + /** + * Get list of added links (must not be NULL). + * @return list of added links (must not be NULL) + */ public List getAddedLinks() { return addedLinks; } + /** + * Get list of deleted links (must not be NULL). + * @return list of deleted links (must not be NULL) + */ public List getDeletedLinks() { return deletedLinks; } - } diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/DeltaLink.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/DeltaLink.java index 866fb1fc9..052e71c91 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/DeltaLink.java +++ b/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; } diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Entity.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Entity.java index 32a543e48..7042b9a76 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Entity.java +++ b/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; diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/EntityCollection.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/EntityCollection.java index 8b6f1df64..adb43dcb2 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/EntityCollection.java +++ b/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; diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/GeoUtils.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/GeoUtils.java index 44218925f..6b086f0d3 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/GeoUtils.java +++ b/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; diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Link.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Link.java index 35acb3123..cde7dc5e0 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Link.java +++ b/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 null. - * @param bindingLinks + * @param bindingLinks list of binding link names */ public void setBindingLinks(final List bindingLinks) { this.bindingLinks = bindingLinks; diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Linked.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Linked.java index 9833af45b..ccc081bf6 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Linked.java +++ b/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 associationLinks = new ArrayList(); diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Operation.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Operation.java index faed25639..4b2580177 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Operation.java +++ b/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; diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Parameter.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Parameter.java index c6ee347e0..a85778085 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Parameter.java +++ b/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; diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Property.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Property.java index 00acc53d3..8593c66eb 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Property.java +++ b/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 null (value == null) or the type is "Edm.Null". + * @return true if this property is null (value == null) + * or the type is "Edm.Null". Otherwise false. + */ @Override public boolean isNull() { return getValue() == null || "Edm.Null".equals(getType()); diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Valuable.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Valuable.java index d71771b1b..c275ae795 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/Valuable.java +++ b/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 null. + * @return true if value is null, otherwise false + */ 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; } diff --git a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ValueType.java b/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ValueType.java index a077b518c..62708bf9a 100644 --- a/lib/commons-api/src/main/java/org/apache/olingo/commons/api/data/ValueType.java +++ b/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; }