diff --git a/geo/src/main/java/com/ibm/common/geojson/AS1Position.java b/geo/src/main/java/com/ibm/common/geojson/AS1Position.java index 2e4f886..4b2ab37 100644 --- a/geo/src/main/java/com/ibm/common/geojson/AS1Position.java +++ b/geo/src/main/java/com/ibm/common/geojson/AS1Position.java @@ -30,6 +30,11 @@ import com.ibm.common.activitystreams.ASObject; /** * Represents an Activity Streams 1.0 style position object + * see (https://github.com/activitystreams/activity-schema/blob/master/activity-schema.md) + * + * Use of the AS1Position object is deprecated. Use the GeoJSON mechanisms + * instead + * * @author james * @deprecated Use Position */ @@ -43,14 +48,29 @@ public final class AS1Position objectType("position"); } + /** + * Set the latitude + * @param latitude float + * @return Builder + */ public Builder latitude(float latitude) { return set("latitude", max(0f,min(90.0f,latitude))); } + /** + * Set the longitude + * @param longitude float + * @return Builder + */ public Builder longitude(float longitude) { return set("longitude", max(-180.0f,min(180.0f,longitude))); } + /** + * Set the altitude + * @param altitude float + * @return Builder + */ public Builder altitude(float altitude) { return set("altitude", altitude); } @@ -66,18 +86,33 @@ public final class AS1Position super(builder); } + /** + * Get the latitude + * @return float + */ public float latitude() { return max(0f,min(90.0f,getFloat("latitude"))); } + /** + * Get the longitude + * @return float + */ public float longitude() { return max(-180.0f,min(180.0f,getFloat("longitude"))); } + /** + * Get the altitude. If the altitude property is not set, this + * will return Float.MIN_VALUE; + * @return float + */ public float altitude() { - return getFloat("altitude"); + return getFloat("altitude", Float.MIN_VALUE); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/geo/src/main/java/com/ibm/common/geojson/Address.java b/geo/src/main/java/com/ibm/common/geojson/Address.java index 0cd651e..4148a4f 100644 --- a/geo/src/main/java/com/ibm/common/geojson/Address.java +++ b/geo/src/main/java/com/ibm/common/geojson/Address.java @@ -25,6 +25,14 @@ import java.io.ObjectStreamException; import com.ibm.common.activitystreams.ASObject; +/** + * A simple non-GeoJSON Address object modelled after the + * legacy Activity Streams 1.0 Address object + * (see https://github.com/activitystreams/activity-schema/blob/master/activity-schema.md) + * + * @author james + * + */ public final class Address extends ASObject { @@ -35,30 +43,65 @@ public final class Address objectType("address"); } + /** + * The full mailing address formatted for display or use + * with a printed mailing label. + * @param formatted String + * @return Builder + */ public Builder formatted(String formatted) { return set("formatted", formatted); } + /** + * The street address including house number, street name, P.O. Box, + * apartment or unit number and extended multi-line address information. + * @param streetAddress String + * @return Builder + */ public Builder streetAddress(String streetAddress) { return set("streetAddress", streetAddress); } + /** + * The city or locality + * @param locality String + * @return Builder + */ public Builder locality(String locality) { return set("locality", locality); } + /** + * The state or region + * @param region String + * @return Builder + */ public Builder region(String region) { return set("region", region); } + /** + * The zip or postal code + * @param postalCode String + * @return Builder + */ public Builder postalCode(String postalCode) { return set("postalCode", postalCode); } + /** + * The country name component + * @param country String + * @return Builder + */ public Builder country(String country) { return set("country", country); } + /** + * Get the completed Address object + */ @Override public Address get() { return new Address(this); @@ -70,30 +113,58 @@ public final class Address super(builder); } + /** + * The full mailing address formatted for display or use + * with a printed mailing label. + * @return String + */ public String formatted() { return getString("formatted"); } + /** + * The street address including house number, street name, P.O. Box, + * apartment or unit number and extended multi-line address information. + * @return String + */ public String streetAddress() { return getString("streetAddress"); } + /** + * The city or locality + * @return String + */ public String locality() { return getString("locality"); } + /** + * The state or region + * @return String + */ public String region() { return getString("region"); } + /** + * The zip or postal code + * @return String + */ public String postalCode() { return getString("postalCode"); } + /** + * The country name component + * @return String + */ public String country() { return getString("country"); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/geo/src/main/java/com/ibm/common/geojson/BoundingBox.java b/geo/src/main/java/com/ibm/common/geojson/BoundingBox.java index b559aa5..57f39a6 100644 --- a/geo/src/main/java/com/ibm/common/geojson/BoundingBox.java +++ b/geo/src/main/java/com/ibm/common/geojson/BoundingBox.java @@ -31,6 +31,10 @@ import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableSortedSet; import com.google.common.collect.Iterables; +/** + * A GeoJSON Bounding Box (see http://geojson.org/geojson-spec.html#bounding-boxes) + * @author james + */ public final class BoundingBox implements Iterable, Serializable { @@ -114,6 +118,11 @@ public final class BoundingBox zset.build()); } + /** + * Calculate the Bounding Box for a collection of Polygon objects + * @param polygons Iterable<Polygon> + * @return BoundingBox + */ public static BoundingBox calculateBoundingBoxPolygons(Iterable polygons) { ImmutableSortedSet.Builder xset = ImmutableSortedSet.naturalOrder(); diff --git a/geo/src/main/java/com/ibm/common/geojson/CRS.java b/geo/src/main/java/com/ibm/common/geojson/CRS.java index 9ef9dd2..c71d9a4 100644 --- a/geo/src/main/java/com/ibm/common/geojson/CRS.java +++ b/geo/src/main/java/com/ibm/common/geojson/CRS.java @@ -30,6 +30,11 @@ import com.google.common.base.Objects; import com.google.common.base.Supplier; import com.google.common.collect.ImmutableMap; +/** + * A GeoJSON Coordinate Reference System description + * see http://geojson.org/geojson-spec.html#coordinate-reference-system-objects + * @author james + */ public final class CRS implements Iterable, Serializable { diff --git a/geo/src/main/java/com/ibm/common/geojson/Feature.java b/geo/src/main/java/com/ibm/common/geojson/Feature.java index 3edf64f..bbef2c9 100644 --- a/geo/src/main/java/com/ibm/common/geojson/Feature.java +++ b/geo/src/main/java/com/ibm/common/geojson/Feature.java @@ -30,6 +30,11 @@ import java.util.Map; import com.google.common.base.Supplier; import com.google.common.collect.ImmutableMap; +/** + * A GeoJSON Feature Object + * see http://geojson.org/geojson-spec.html#feature-objects + * @author james + */ public final class Feature extends GeoObject implements Iterable { diff --git a/geo/src/main/java/com/ibm/common/geojson/FeatureCollection.java b/geo/src/main/java/com/ibm/common/geojson/FeatureCollection.java index aa560ad..6a28b15 100644 --- a/geo/src/main/java/com/ibm/common/geojson/FeatureCollection.java +++ b/geo/src/main/java/com/ibm/common/geojson/FeatureCollection.java @@ -30,6 +30,12 @@ import com.google.common.base.Supplier; import com.google.common.collect.ImmutableList; import com.google.common.collect.Iterables; +/** + * A GeoJSON FeatureCollection object + * see http://geojson.org/geojson-spec.html#feature-collection-objects + * @author james + * + */ public final class FeatureCollection extends GeoObject implements Iterable { diff --git a/geo/src/main/java/com/ibm/common/geojson/GeoMakers.java b/geo/src/main/java/com/ibm/common/geojson/GeoMakers.java index 55dfe6e..efd7683 100644 --- a/geo/src/main/java/com/ibm/common/geojson/GeoMakers.java +++ b/geo/src/main/java/com/ibm/common/geojson/GeoMakers.java @@ -21,6 +21,11 @@ */ package com.ibm.common.geojson; +/** + * Makers for the various GeoJSON object types + * @author james + * + */ @SuppressWarnings("deprecation") public final class GeoMakers { diff --git a/geo/src/main/java/com/ibm/common/geojson/GeoObject.java b/geo/src/main/java/com/ibm/common/geojson/GeoObject.java index 0e47e3f..65fc410 100644 --- a/geo/src/main/java/com/ibm/common/geojson/GeoObject.java +++ b/geo/src/main/java/com/ibm/common/geojson/GeoObject.java @@ -30,6 +30,13 @@ import com.google.common.base.Supplier; import static com.google.common.collect.ImmutableMap.copyOf; import static com.google.common.collect.Maps.newLinkedHashMap; +/** + * The base class for all GeoJSON objects. The type of object is identified + * by the type() property. + * @author james + * + * @param + */ @SuppressWarnings("unchecked") public abstract class GeoObject> implements Serializable { @@ -57,29 +64,60 @@ public abstract class GeoObject> protected Map data = newLinkedHashMap(); + /** + * Auto-calculate the bounding box when the object is created + * @return Builder + */ public B calculateBoundingBox() { this.withBoundingBox = true; return (B)this; } + /** + * Use the given object as a template when creating this one + * @param geo GeObject<?> + * @return Builder + */ protected B from(GeoObject geo) { data.putAll(geo.data); return (B)this; } + /** + * Set the object type + * @param type Type + * @return Builder + */ public B type(Type type) { this.type = type; return (B)this; } + /** + * Set the CRS + * @param crs CRS + * @return Builder + */ public B crs(CRS crs) { return set("crs", crs); } + /** + * Set the bounding box explicitly + * @param bbox BoundingBox + * @return Builder + * @see GeoObject.Builder.calculateBoundingBox() + */ public B boundingBox(BoundingBox bbox) { return set("bbox", bbox); } + /** + * Set an additional property on this object + * @param name String + * @param val Object + * @return Builder + */ public B set(String name, Object val) { if (val != null) this.data.put(name,val); @@ -88,6 +126,9 @@ public abstract class GeoObject> return (B)this; } + /** + * Get the built object + */ public final G get() { preGet(); G g = doGet(); @@ -107,6 +148,10 @@ public abstract class GeoObject> this.data = copyOf(builder.data); } + /** + * Return the type of object + * @return Type + */ public Type type() { return type; } @@ -124,14 +169,26 @@ public abstract class GeoObject> return data.containsKey(name); } + /** + * Return the CRS for this object + * @return CRS + */ public CRS crs() { return this.get("crs", null); } + /** + * Return the bounding box for this object + * @return BoundingBox + */ public BoundingBox boundingBox() { return this.get("bbox", null); } + /** + * Return a copy of this object with a calculated bounding box + * @return G (a copy of this object) + */ public final G withBoundingBox() { return has("bbox") ? (G)this : makeWithBoundingBox(); diff --git a/geo/src/main/java/com/ibm/common/geojson/GeometryCollection.java b/geo/src/main/java/com/ibm/common/geojson/GeometryCollection.java index c71a65c..57e11d8 100644 --- a/geo/src/main/java/com/ibm/common/geojson/GeometryCollection.java +++ b/geo/src/main/java/com/ibm/common/geojson/GeometryCollection.java @@ -29,6 +29,12 @@ import java.util.Iterator; import com.google.common.collect.ImmutableList; import com.google.common.collect.Iterables; +/** + * A GeoJSON GeometryCollection object + * see http://geojson.org/geojson-spec.html#geometry-collection + * @author james + * + */ public final class GeometryCollection extends Geometry> { diff --git a/geo/src/main/java/com/ibm/common/geojson/LineString.java b/geo/src/main/java/com/ibm/common/geojson/LineString.java index 88504c2..8f4c79f 100644 --- a/geo/src/main/java/com/ibm/common/geojson/LineString.java +++ b/geo/src/main/java/com/ibm/common/geojson/LineString.java @@ -35,6 +35,34 @@ import com.google.common.base.Supplier; import com.google.common.collect.ImmutableList; import com.ibm.common.geojson.Geometry.CoordinateGeometry; +/** + * A GeoJSON LineString object + * See http://geojson.org/geojson-spec.html#linestring. + * + * The LineString can optionally be a Linear Ring if there are at least four + * positions and the first and last position are equivalent. + * + * 
+ *   LineString regularLineString = 
+ *     GeoMakers.linestring()
+ *       .add(1,2)
+ *       .add(2,3)
+ *       .get();
+ *   // includes points (1,2) and (2,3)
+ *       
+ *   LineString linearRing = 
+ *     GeoMakers.linestring()
+ *       .linearRing()
+ *       .add(1,2)
+ *       .add(2,3)
+ *       .add(3,4)
+ *       .get()
+ *   // includes points (1,2), (2,3), (3,4) and (1,2)
+ *
+ * + * @author james + * + */ public final class LineString extends CoordinateGeometry> { @@ -56,6 +84,10 @@ public final class LineString type(Type.LINESTRING); } + /** + * Specify that this LineString is a linearring + * @return Builder + */ public Builder linearRing() { return linearRing(true); } @@ -65,6 +97,12 @@ public final class LineString return this; } + /** + * Add one or more positions to this linestring + * @param position Position + * @param positions Position[] optional vararg + * @return Builder + */ public Builder add(Position position, Position... positions) { this.positions.add(position); if (positions != null) @@ -73,19 +111,42 @@ public final class LineString return this; } + /** + * Add a single position to this linestring + * @param x float + * @param y float + * @return Builder + */ public Builder add(float x, float y) { return add(GeoObject.position(x, y)); } + /** + * Add a single position to this linestring + * @param position Supplier<Position> + * @return Builder + */ public Builder add(Supplier position) { return add(position.get()); } + /** + * Add one or more positions to this linestring + * @param positions Iterable<Position> + * @return Builder + */ public Builder add(Iterable positions) { this.positions.addAll(positions); return this; } + /** + * Add a single position to this linestring + * @param x float + * @param y float + * @param z float + * @return Builder + */ public Builder add(float x, float y, float z) { return add(GeoObject.position(x,y,z)); } @@ -122,6 +183,10 @@ public final class LineString } @Override + /** + * Get this LineStrings positions + * @return Iterable<Position> + */ public Iterable coordinates() { Iterable pos = super.coordinates(); if (!ring) @@ -138,6 +203,9 @@ public final class LineString return coordinates().iterator(); } + /** + * Return a copy of this linestring with a calculated bounding box + */ @Override public LineString makeWithBoundingBox() { return new LineString.Builder() @@ -146,6 +214,8 @@ public final class LineString .boundingBox(calculateBoundingBoxPositions(this)) .get(); } + + // Java Serialization support Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); diff --git a/geo/src/main/java/com/ibm/common/geojson/MultiLineString.java b/geo/src/main/java/com/ibm/common/geojson/MultiLineString.java index c5297d1..14df947 100644 --- a/geo/src/main/java/com/ibm/common/geojson/MultiLineString.java +++ b/geo/src/main/java/com/ibm/common/geojson/MultiLineString.java @@ -30,6 +30,12 @@ import com.google.common.base.Supplier; import com.google.common.collect.ImmutableList; import com.ibm.common.geojson.Geometry.CoordinateGeometry; +/** + * A GeoJSON MultiLineString object + * see http://geojson.org/geojson-spec.html#multilinestring + * @author james + * + */ public final class MultiLineString extends CoordinateGeometry> { @@ -43,6 +49,12 @@ public final class MultiLineString type(Type.MULTILINESTRING); } + /** + * Add one or more LineStrings + * @param line LineString + * @param lines LineString[] optional vararg + * @return Builder + */ public Builder add(LineString line, LineString... lines) { this.strings.add(line); if (lines != null) @@ -51,10 +63,20 @@ public final class MultiLineString return this; } + /** + * Add a single LineString + * @param line Supplier<LineString> + * @return Builder + */ public Builder add(Supplier line) { return add(line.get()); } + /** + * Add one or more LineStrings + * @param lines Iterable<LineString> + * @return Builder + */ public Builder add(Iterable lines) { this.strings.addAll(lines); return this; @@ -64,6 +86,10 @@ public final class MultiLineString return new MultiLineString(this); } + /** + * Get this objects collection of LineStrings + * @return Iterable<LineString> + */ @Override protected Iterable coordinates() { return strings.build(); @@ -81,6 +107,10 @@ public final class MultiLineString return coordinates().iterator(); } + /** + * Copy this object with a calculated bounding box + * @return MultiLineString + */ @Override protected MultiLineString makeWithBoundingBox() { return new MultiLineString.Builder() diff --git a/geo/src/main/java/com/ibm/common/geojson/MultiPoint.java b/geo/src/main/java/com/ibm/common/geojson/MultiPoint.java index 05d112b..b90156a 100644 --- a/geo/src/main/java/com/ibm/common/geojson/MultiPoint.java +++ b/geo/src/main/java/com/ibm/common/geojson/MultiPoint.java @@ -30,6 +30,12 @@ import com.ibm.common.geojson.Geometry.CoordinateGeometry; import static com.ibm.common.geojson.BoundingBox.calculateBoundingBoxPositions; +/** + * A GeoJSON MultiPoint object + * see http://geojson.org/geojson-spec.html#multipoint + * @author james + * + */ public final class MultiPoint extends CoordinateGeometry> { @@ -43,6 +49,12 @@ public final class MultiPoint type(GeoObject.Type.MULTIPOINT); } + /** + * Add one or more positions + * @param position Position + * @param positions Position[] optional vararg + * @return Builder + */ public Builder add(Position position, Position... positions) { list.add(position); if (positions != null) @@ -50,19 +62,42 @@ public final class MultiPoint return this; } + /** + * Add one or more positions + * @param positions Iterable<Position> + * @return Builder + */ public Builder add(Iterable positions) { list.addAll(positions); return this; } + /** + * Add a position + * @param pos Supplier<Position> + * @return Builder + */ public Builder add(Supplier pos) { return add(pos.get()); } + /** + * Add a position + * @param x float + * @param y float + * @return Builder + */ public Builder add(float x, float y) { return add(GeoObject.position(x, y)); } + /** + * Add a position + * @param x float + * @param y float + * @param z float + * @return Builder + */ public Builder add(float x, float y, float z) { return add(GeoObject.position(x,y,z)); } @@ -89,6 +124,10 @@ public final class MultiPoint return coordinates().iterator(); } + /** + * Return a copy of this object with a calculated bounding box + * @return MultiPoint + */ @Override protected MultiPoint makeWithBoundingBox() { return new MultiPoint.Builder() diff --git a/geo/src/main/java/com/ibm/common/geojson/MultiPolygon.java b/geo/src/main/java/com/ibm/common/geojson/MultiPolygon.java index df3398e..0727c93 100644 --- a/geo/src/main/java/com/ibm/common/geojson/MultiPolygon.java +++ b/geo/src/main/java/com/ibm/common/geojson/MultiPolygon.java @@ -30,6 +30,12 @@ import com.google.common.base.Supplier; import com.google.common.collect.ImmutableList; import com.ibm.common.geojson.Geometry.CoordinateGeometry; +/** + * A GeoJSON MultiPolygon object. + * see http://geojson.org/geojson-spec.html#multipolygon + * @author james + * + */ public final class MultiPolygon extends CoordinateGeometry>{ @@ -43,6 +49,12 @@ public final class MultiPolygon type(Type.MULTIPOLYGON); } + /** + * Add one or more Polygons + * @param poly Polygon + * @param polys Polygon[] optional vararg + * @return Builder + */ public Builder add(Polygon poly, Polygon... polys) { // TODO: Check hole requirement this.strings.add(poly); @@ -52,10 +64,20 @@ public final class MultiPolygon return this; } + /** + * Add a Polygon + * @param poly Supplier<Polygon> + * @return Builder + */ public Builder add(Supplier poly) { return add(poly.get()); } + /** + * Add one ore more Polygons + * @param polygons Iterable<Polygon> + * @return Builder + */ public Builder add(Iterable polygons) { this.strings.addAll(polygons); return this; @@ -82,6 +104,10 @@ public final class MultiPolygon return coordinates().iterator(); } + /** + * Return a copy of this object with a calculated bounding box + * @return MultiPolygon + */ @Override protected MultiPolygon makeWithBoundingBox() { return new MultiPolygon.Builder() diff --git a/geo/src/main/java/com/ibm/common/geojson/Place.java b/geo/src/main/java/com/ibm/common/geojson/Place.java index 2dda6ae..e61e461 100644 --- a/geo/src/main/java/com/ibm/common/geojson/Place.java +++ b/geo/src/main/java/com/ibm/common/geojson/Place.java @@ -26,6 +26,15 @@ import java.io.ObjectStreamException; import com.google.common.base.Supplier; import com.ibm.common.activitystreams.ASObject; +/** + * A legacy Activity Streams 1.0 Place object + * see https://github.com/activitystreams/activity-schema/blob/master/activity-schema.md. + * + * Place objects have additional address, position and geo properties that + * describe the location. + * @author james + * + */ public final class Place extends ASObject { public static final class Builder @@ -35,25 +44,52 @@ public final class Place extends ASObject { objectType("place"); } + /** + * Set the address + * @param address Address + * @return Builder + */ public Builder address(Address address) { return set("address", address); } + /** + * Set the address + * @param address Supplier<Address> + * @return Builder + */ public Builder address(Supplier
address) { return address(address.get()); } - @SuppressWarnings("deprecation") + /** + * Set the position + * @deprecated + * @param position AS1Position + * @return Builder + */ public Builder position(AS1Position position) { return set("position", position); } - @SuppressWarnings("deprecation") + /** + * Set the position + * @deprecated + * @param position Supplier<AS1Position> + * @return Builder + */ public Builder position(Supplier position) { return position(position.get()); } - @SuppressWarnings("deprecation") + /** + * Set the position + * @param latitude float + * @param longitude float + * @param altitude float + * @return Builder + * @deprecated + */ public Builder position( float latitude, float longitude, @@ -61,10 +97,20 @@ public final class Place extends ASObject { return position(GeoMakers.as1Position(latitude, longitude, altitude)); } + /** + * Set the geo property + * @param geo GeoObject<?> Any GeoJSON object can be used + * @return Builder + */ public Builder geo(GeoObject geo) { return set("geo", geo); } + /** + * Set the geo property + * @param geo Supplier<? extends GeoObject<?>> Any GeoJSON object can be used + * @return Builder + */ public Builder geo(Supplier> geo) { return geo(geo.get()); } @@ -80,15 +126,27 @@ public final class Place extends ASObject { super(builder); } + /** + * Get the address + * @return Address + */ public Address address() { return this.
get("address"); } - @SuppressWarnings("deprecation") + /** + * Get the position + * @deprecated + * @return AS1Position + */ public AS1Position position() { return this.get("position"); } + /** + * Get the geo property + * @return <G extends GeoObject<?>>G + */ public >G geo() { return this.get("geo"); } diff --git a/geo/src/main/java/com/ibm/common/geojson/Point.java b/geo/src/main/java/com/ibm/common/geojson/Point.java index cdf026c..2ff83b0 100644 --- a/geo/src/main/java/com/ibm/common/geojson/Point.java +++ b/geo/src/main/java/com/ibm/common/geojson/Point.java @@ -31,6 +31,15 @@ import static com.ibm.common.geojson.BoundingBox.calculateBoundingBox; import com.ibm.common.geojson.Geometry.CoordinateGeometry; +/** + * A GeoJSON Point object + * see http://geojson.org/geojson-spec.html#point. + * + * A Point object represents a single Position + * + * @author james + * + */ public final class Point extends CoordinateGeometry { @@ -43,21 +52,44 @@ public final class Point type(GeoObject.Type.POINT); } - public Builder position(float x, float y, float z) { - this.position = GeoObject.position(x, y, z); + /** + * Set the position + * @param northing float + * @param easting float + * @param altitude float + * @return Builder + */ + public Builder position(float northing, float easting, float altitude) { + this.position = GeoObject.position(northing, easting, altitude); return this; } - public Builder position(float x, float y) { - this.position = GeoObject.position(x,y); + /** + * Set the position + * @param northing float + * @param easting float + * @return Builder + */ + public Builder position(float northing, float easting) { + this.position = GeoObject.position(northing,easting); return this; } + /** + * Set the position + * @param position Position + * @return Builder + */ public Builder position(Position position) { this.position = position; return this; } + /** + * Set the position + * @param position Supplier<Position> + * @return Builder + */ public Builder position(Supplier position) { return position(position.get()); } diff --git a/geo/src/main/java/com/ibm/common/geojson/Polygon.java b/geo/src/main/java/com/ibm/common/geojson/Polygon.java index 252e47d..e447f2b 100644 --- a/geo/src/main/java/com/ibm/common/geojson/Polygon.java +++ b/geo/src/main/java/com/ibm/common/geojson/Polygon.java @@ -31,6 +31,12 @@ import com.google.common.base.Supplier; import com.google.common.collect.ImmutableList; import com.ibm.common.geojson.Geometry.CoordinateGeometry; +/** + * A GeoJSON Polygon object + * see http://geojson.org/geojson-spec.html#polygon + * @author james + * + */ public final class Polygon extends CoordinateGeometry> { @@ -44,6 +50,12 @@ public final class Polygon type(Type.POLYGON); } + /** + * Add one or more LineStrings + * @param line LineString + * @param lines LineString[] optional vararg + * @return Builder + */ public Builder add(LineString line, LineString... lines) { checkArgument(line.linearRing(), "Polygon coordinates MUST be Linear Rings"); // TODO: Check hole requirement @@ -54,10 +66,20 @@ public final class Polygon return this; } + /** + * Add a LineString + * @param line Supplier<LineString> + * @return Builder + */ public Builder add(Supplier line) { return add(line.get()); } + /** + * Add one or more LineStrings + * @param lines Iterable<LineString> + * @return Builder + */ public Builder add(Iterable lines) { this.strings.addAll(lines); return this; diff --git a/geo/src/main/java/com/ibm/common/geojson/Position.java b/geo/src/main/java/com/ibm/common/geojson/Position.java index 35f00d8..6bc4605 100755 --- a/geo/src/main/java/com/ibm/common/geojson/Position.java +++ b/geo/src/main/java/com/ibm/common/geojson/Position.java @@ -33,6 +33,16 @@ import com.google.common.base.Supplier; import com.google.common.collect.ImmutableList; import com.google.common.primitives.Floats; +/** + * A GeoJSON Position + * see http://geojson.org/geojson-spec.html#positions. + * + * Position objects consist primarily of three distinct values: + * a northing (latitude or x), easting (longitude or y) and altitude (z). + * + * @author james + * + */ public final class Position implements Iterable, Serializable { diff --git a/geo/src/main/java/com/ibm/common/geojson/as2/GeoModule.java b/geo/src/main/java/com/ibm/common/geojson/as2/GeoModule.java index f7f38e4..d58ce31 100644 --- a/geo/src/main/java/com/ibm/common/geojson/as2/GeoModule.java +++ b/geo/src/main/java/com/ibm/common/geojson/as2/GeoModule.java @@ -32,6 +32,21 @@ import com.ibm.common.geojson.Address; import com.ibm.common.geojson.GeoObject; import com.ibm.common.geojson.Place; +/** + * Enables the use of the GeoJSON extensions with Activity Streams 2.0 + * + * 
+ *   import com.ibm.common.geojson.as2.GeoModule;
+ *   import com.ibm.common.activitystreams.IO;
+ *   
+ *   //...
+ *   
+ *   IO io = IO.makeDefault(GeoModule.instance);
+ *   
+ *
+ * @author james + * + */ @SuppressWarnings("deprecation") public final class GeoModule implements Module { diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/AudioVisual.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/AudioVisual.java index 4fbb17b..559635a 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/AudioVisual.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/AudioVisual.java @@ -26,24 +26,50 @@ import java.io.ObjectStreamException; import com.google.common.base.Supplier; import com.ibm.common.activitystreams.ASObject; +/** + * For the legacy "audio" and "video" objectTypes. These have + * a String "embedCode" property whose value specifies a + * snippet of HTML for embedding the resource and a stream + * MediaLink property. + * + * @author james + */ public final class AudioVisual extends ASObject { public static final class Builder extends ASObject.AbstractBuilder { + /** + * Set the embedCode + * @param embed String + * @return Builder + */ public Builder embedCode(String embed) { return set("embedCode", embed); } + /** + * Set the stream MediaLink + * @param mediaLink MediaLink + * @return Builder + */ public Builder stream(MediaLink mediaLink) { return set("stream", mediaLink); } + /** + * Set the stream MediaLink + * @param mediaLink Supplier<MediaLink> + * @return Builder + */ public Builder stream(Supplier mediaLink) { return stream(mediaLink.get()); } + /** + * Get the built AudioVisual object + */ public AudioVisual get() { return new AudioVisual(this); } @@ -54,14 +80,24 @@ public final class AudioVisual super(builder); } + /** + * Get the embedCode property. This should be a snippet of HTML + * @return String + */ public String embedCode() { return getString("embedCode"); } + /** + * Get the stream MediaLink or null if not provided + * @return MediaLink + */ public MediaLink stream() { return this.get("stream"); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Binary.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Binary.java index cf7ebc7..5ac6e4e 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Binary.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Binary.java @@ -35,6 +35,22 @@ import com.google.common.io.BaseEncoding; import com.google.common.net.MediaType; import com.ibm.common.activitystreams.ASObject; +/** + * The legacy "binary" objectType. + * + * 
+ *   InputStream in = ...
+ *   // will base64 encode, gzip compress and md5 sum the input data
+ *   // will also set the length property accordingly
+ *   Binary binary = 
+ *     LegacyMakers.binary()
+ *       .gzipData(in)
+ *       .get();
+ *
+ * + * @author james + * + */ public final class Binary extends ASObject { @@ -45,20 +61,48 @@ public final class Binary objectType("binary"); } + /** + * Set the input data without any compression. Will automatically + * set calculate the md5 sum and length properties + * @param in InputStream + * @return Builder + * @throws IOException + */ public Builder data( InputStream in) throws IOException { return data(in,null); } + /** + * Set the input data with GZip compression. Will automatically + * set calculate the md5 sum and length properties + * @param in InputStream + * @return Builder + * @throws IOException + */ public Builder gzipData(InputStream in) throws IOException { return data(in, Compression.GZipCompression); } + /** + * Set the input data with Deflate compression. Will automatically + * set calculate the md5 sum and length properties + * @param in InputStream + * @return Builder + * @throws IOException + */ public Builder deflateData(InputStream in) throws IOException { return data(in, Compression.DeflateCompression); } + /** + * Set the input data the given Compression. Will automatically + * set calculate the md5 sum and length properties + * @param in InputStream + * @return Builder + * @throws IOException + */ public Builder data( InputStream in, Compression compression) @@ -88,19 +132,40 @@ public final class Binary return set("data",writer.toString()); } + /** + * Manually set the md5 properties (this is not recommended. calling the data + * methods will automatically generate the md5 checksum for you) + * + * @param md5 String + * @return Builder + */ public Builder md5(String md5) { return set("md5", md5); } + /** + * Set the fileUrl property + * @param fileUrl String + * @return Builder + */ public Builder fileUrl(String fileUrl) { return set("fileUrl", fileUrl); } + /** + * Set the MIME Media Type using the Legacy "mimeType" property name + * rather than the AS 2.0 "mediaType" property name + * @param mt MediaType + * @return Builder + */ @Override public Builder mediaType(MediaType mt) { return set("mimeType", mt); } + /** + * Get the built Binary object + */ public Binary get() { return new Binary(this); } @@ -111,34 +176,69 @@ public final class Binary super(builder); } + /** + * Get the fileUrl property + * @return String + */ public String fileUrl() { return getString("fileUrl"); } + /** + * Get the length property + * @return long + */ public long length() { return getLong("length"); } + /** + * Get the compression property value (typically "gzip" or "deflate") + * @return String + */ public String compression() { return getString("compression"); } + /** + * True if compression = gzip + * @return boolean + */ public boolean isGzip() { return "gzip".equalsIgnoreCase(compression()); } + /** + * True if compression = deflate + * @return boolean + */ public boolean isDeflate() { return "deflate".equalsIgnoreCase(compression()); } + /** + * Return the md5 checksum + * @return String + */ public String md5() { return getString("md5"); } + /** + * Return the literal string content of the data property. + * This will be base64 encoded and optionally compressed + * @return String + */ public String data() { return getString("data"); } + /** + * Return an InputStream for reading the data. Will + * decompress and base64 decode as necessary + * @return InputStream + * @throws IOException + */ public InputStream read() throws IOException { Compression compression = isGzip() ? Compression.GZipCompression : @@ -147,6 +247,12 @@ public final class Binary return read(compression); } + /** + * Return an InputStream for reading the data + * @param compression Compression + * @return InputStream + * @throws IOException + */ public InputStream read(Compression compression) throws IOException { StringReader reader = new StringReader(data()); InputStream in = BaseEncoding.base64Url().decodingStream(reader); @@ -157,10 +263,16 @@ public final class Binary return in; } + /** + * Return the MIME MediaType using the legacy "mimeType" property name + * rather than the AS 2.0 "mediaType" name + */ @Override public MediaType mediaType() { return this.get("mimeType"); } + + // Java Serialization Support Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Bookmark.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Bookmark.java index 16eae79..313f567 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Bookmark.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Bookmark.java @@ -25,6 +25,10 @@ import java.io.ObjectStreamException; import com.ibm.common.activitystreams.ASObject; +/** + * The legacy "bookmark" objectType + * @author james + */ public class Bookmark extends ASObject { @@ -35,10 +39,18 @@ public class Bookmark objectType("bookmark"); } + /** + * Set the targetUrl property + * @param url String + * @return Builder + */ public Builder targetUrl(String url) { return set("targetUrl", url); } - + + /** + * Get the built Bookmark object + */ public Bookmark get() { return new Bookmark(this); } @@ -49,10 +61,16 @@ public class Bookmark super(builder); } + /** + * Get the targetUrl property + * @return String + */ public String targetUrl() { return getString("targetUrl"); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Compression.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Compression.java index 0264a4a..08f8912 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Compression.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Compression.java @@ -29,6 +29,13 @@ import java.util.zip.DeflaterOutputStream; import java.util.zip.GZIPInputStream; import java.util.zip.GZIPOutputStream; +/** + * Compression utility for use with the Binary object + * @author james + * + * @param <O extends OutputStream> + * @param <I extends InputStream> + */ public interface Compression { String label(); O compressor(OutputStream wrap) throws IOException; diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Event.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Event.java index 5f2d327..40b3c07 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Event.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Event.java @@ -27,6 +27,10 @@ import com.google.common.base.Supplier; import com.ibm.common.activitystreams.ASObject; import com.ibm.common.activitystreams.Collection; +/** + * The legacy "event" objectType + * @author james + */ public class Event extends ASObject { @@ -36,55 +40,119 @@ public class Event Builder() { objectType("event"); } - + + /** + * Set the attendedBy Collection property + * @param collection Collection + * @return Builder + */ public Builder attendedBy(Collection collection) { return set("attendedBy", collection); } + /** + * Set the attendedBy Collection property + * @param collection Collection + * @return Builder + */ public Builder attendedBy(Supplier collection) { return attendedBy(collection.get()); } + /** + * Set the attending Collection property + * @param collection Collection + * @return Builder + */ public Builder attending(Collection collection) { return set("attending", collection); } + /** + * Set the attending Collection property + * @param collection Collection + * @return Builder + */ public Builder attending(Supplier collection) { return attending(collection.get()); } + /** + * Set the invited Collection property + * @param collection Collection + * @return Builder + */ public Builder invited(Collection collection) { return set("invited", collection); } + /** + * Set the invited Collection property + * @param collection Collection + * @return Builder + */ public Builder invited(Supplier collection) { return invited(collection.get()); } + /** + * Set the maybeAttending Collection property + * @param collection Collection + * @return Builder + */ public Builder maybeAttending(Collection collection) { return set("maybeAttending", collection); } + /** + * Set the maybeAttending Collection property + * @param collection Collection + * @return Builder + */ public Builder maybeAttending(Supplier collection) { return maybeAttending(collection.get()); } + /** + * Set the notAttendedBy Collection property + * @param collection Collection + * @return Builder + */ public Builder notAttendedBy(Collection collection) { return set("notAttendedBy", collection); } + /** + * Set the notAttendedBy Collection property + * @param collection Collection + * @return Builder + */ public Builder notAttendedBy(Supplier collection) { return notAttendedBy(collection.get()); } + /** + * Set the notAttending Collection property + * @param collection Collection + * @return Builder + */ public Builder notAttending(Collection collection) { return set("notAttending", collection); } + /** + * Set the notAttending Collection property + * @param collection Collection + * @return Builder + */ public Builder notAttending(Supplier collection) { return notAttending(collection.get()); } + /** + * Get the built Event object + * @return Event + */ public Event get() { return new Event(this); } @@ -95,30 +163,56 @@ public class Event super(builder); } + /** + * Get the attendedBy Collection or null if not provided + * @return Collection + */ public Collection attendedBy() { return this.get("attendedBy"); } + /** + * Get the attending Collection or null if not provided + * @return Collection + */ public Collection attending() { return this.get("attending"); } + /** + * Get the invited Collection or null if not provided + * @return Collection + */ public Collection invited() { return this.get("invited"); } + /** + * Get the maybeAttending Collection or null if not provided + * @return Collection + */ public Collection maybeAttending() { return this.get("maybeAttending"); } + /** + * Get the notAttendedBy Collection or null if not provided + * @return Collection + */ public Collection notAttendedBy() { return this.get("notAttendedBy"); } + /** + * Get the notAttending Collection or null if not provided + * @return Collection + */ public Collection notAttending() { return this.get("notAttending"); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/File.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/File.java index efe5ae9..cdac245 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/File.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/File.java @@ -26,6 +26,10 @@ import java.io.ObjectStreamException; import com.google.common.net.MediaType; import com.ibm.common.activitystreams.ASObject; +/** + * The legacy "file" objectType + * @author james + */ public class File extends ASObject { @@ -36,15 +40,27 @@ public class File objectType("file"); } + /** + * Set the fileUrl property + * @param url String + * @return Builder + */ public Builder fileUrl(String url) { return set("fileUrl", url); } + /** + * Set the MIME mediaType using the legacy "mimeType" property + * name rather than the AS 2.0 "mediaType" property name + */ @Override public Builder mediaType(MediaType mt) { return set("mimeType", mt); } + /** + * Get the built File object + */ public File get() { return new File(this); } @@ -55,15 +71,25 @@ public class File super(builder); } + /** + * Get the MIME mediaType using the legacy "mimeType" property + * name rather than the AS 2.0 "mediaType" property + */ @Override public MediaType mediaType() { return this.get("mimeType"); } + /** + * Get the fileUrl property + * @return + */ public String fileUrl() { return getString("fileUrl"); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Issue.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Issue.java index 9acebe0..7ef0057 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Issue.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Issue.java @@ -26,6 +26,11 @@ import java.io.ObjectStreamException; import com.google.common.collect.ImmutableList; import com.ibm.common.activitystreams.ASObject; +/** + * The legacy "issue" objectType. + * @author james + * + */ public class Issue extends ASObject { @@ -36,6 +41,12 @@ public class Issue objectType("issue"); } + /** + * Set the "types" property + * @param type String + * @param types String... optional vararg of additional types to set + * @return Builder + */ public Builder types(String type, String... types) { ImmutableList.Builder list = ImmutableList.builder(); @@ -46,10 +57,18 @@ public class Issue return types(list.build()); } + /** + * Set the "types" property + * @param types Iterable<String> + * @return Builder + */ public Builder types(Iterable types) { return set("types", types); } + /** + * Get the built Issue object + */ public Issue get() { return new Issue(this); } @@ -60,10 +79,16 @@ public class Issue super(builder); } + /** + * Get the listing of types + * @return Iterable<String> + */ public Iterable types() { return this.>get("types"); } + // Java Serialization Support ` + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyMakers.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyMakers.java index b457db9..bfdae4c 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyMakers.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyMakers.java @@ -24,6 +24,10 @@ package com.ibm.common.activitystreams.legacy; import com.ibm.common.activitystreams.ASObject; import static com.ibm.common.activitystreams.Makers.object; +/** + * Makers for the various Legacy object types + * @author james + */ public final class LegacyMakers { private LegacyMakers() {} diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyModule.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyModule.java index 0315587..b974ccf 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyModule.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyModule.java @@ -31,7 +31,23 @@ import com.ibm.common.activitystreams.internal.Schema; import com.ibm.common.activitystreams.internal.Schema.Builder; import com.ibm.common.activitystreams.util.Module; -public class LegacyModule +/** + * Adds support for legacy objectTypes defined by the original + * Activity Streams 1.0 Schema (see https://github.com/activitystreams/activity-schema/blob/master/activity-schema.md) + * + * 
+ *   import com.ibm.common.activitystreams.IO;
+ *   import com.ibm.common.activitystreams.legacy.LegacyModule;
+ *   
+ *   //...
+ *   
+ *   IO io = IO.makeDefault(LegacyModule.instance);
+ *   
+ *
+ * @author james + * + */ +public final class LegacyModule implements Module { public static final Module instance = new LegacyModule(); diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/MediaLink.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/MediaLink.java index 01869f0..6d1d11e 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/MediaLink.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/MediaLink.java @@ -31,6 +31,11 @@ import com.google.common.collect.ImmutableMap; import com.google.common.collect.Maps; import com.ibm.common.activitystreams.util.AbstractWritable; +/** + * An Activity Streams 1.0 Media Link object. + * @author james + * + */ public final class MediaLink extends AbstractWritable implements Iterable, Serializable { @@ -42,31 +47,67 @@ public final class MediaLink private Map map = Maps.newHashMap(); + /** + * When the media link refers to a video or audio resource, + * the duration property indicates the total length in seconds + * @param duration int + * @return Builder + */ public Builder duration(int duration) { map.put("duration", duration); return this; } + /** + * When the media link refers to an object intended to be + * displayed visually, such as a video or image, the + * height property specifies the display height in terms + * of device independent pixels. + * @param height int + * @return Builder + */ public Builder height(int height) { map.put("height", height); return this; } + /** + * When the media link refers to an object intended to be + * displayed visually, such as a video or image, the + * width property specifies the display width in terms + * of device independent pixels. + * @param height int + * @return Builder + */ public Builder width(int width) { map.put("width", width); return this; } + /** + * The URL of the resource + * @param url String + * @return Builder + */ public Builder url(String url) { map.put("url", url); return this; } + /** + * Set an arbitrary property on the Media Link + * @param key String + * @param val Object + * @return Builder + */ public Builder set(String key, Object val) { map.put(key,val); return this; } + /** + * Get the built MediaLink object + */ public MediaLink get() { return new MediaLink(this); } @@ -80,22 +121,50 @@ public final class MediaLink this.map = ImmutableMap.copyOf(builder.map); } + /** + * Get the url property + * @return + */ public String url() { return (String)map.get("url"); } + /** + * When the media link refers to a video or audio resource, + * the duration property indicates the total length in seconds + * @return int + */ public int duration() { return (Integer)map.get("duration"); } + /** + * When the media link refers to an object intended to be + * displayed visually, such as a video or image, the + * height property specifies the display height in terms + * of device independent pixels. + * @return int + */ public int height() { return (Integer)map.get("height"); } + /** + * When the media link refers to an object intended to be + * displayed visually, such as a video or image, the + * width property specifies the display width in terms + * of device independent pixels. + * @return int + */ public int width() { return (Integer)map.get("width"); } + /** + * Return the given property + * @param key + * @return <T>T + */ @SuppressWarnings("unchecked") public T get(String key) { return (T)map.get(key); @@ -105,6 +174,8 @@ public final class MediaLink return map.keySet().iterator(); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Membership.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Membership.java index 37df4de..2fc43c5 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Membership.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Membership.java @@ -27,19 +27,40 @@ import com.google.common.base.Supplier; import com.ibm.common.activitystreams.ASObject; import com.ibm.common.activitystreams.Collection; +/** + * For the legacy "role", "group" and "team" objectTypes. + * Membership objects include an additional "members" + * collection property. + * + * @author james + * + */ public class Membership extends ASObject { public static final class Builder extends ASObject.AbstractBuilder { + /** + * Set the members collection + * @param collection Collection + * @return Builder + */ public Builder members(Collection collection) { return set("members", collection); } + /** + * Set the members collection + * @param collection Collection + * @return Builder + */ public Builder members(Supplier collection) { return members(collection.get()); } + /** + * Get the built Membership object + */ public Membership get() { return new Membership(this); } @@ -50,10 +71,16 @@ public class Membership extends ASObject { super(builder); } + /** + * Return the members collection + * @return Collection + */ public Collection members() { return this.get("members"); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Question.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Question.java index d164ece..c2f8b18 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Question.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Question.java @@ -28,6 +28,18 @@ import com.google.common.base.Supplier; import com.ibm.common.activitystreams.ASObject; import com.ibm.common.activitystreams.LinkValue; +/** + * The legacy "question" object. Question objects + * have an additional "options" property that lists + * the possible answers to the question. + * + * This implementation varies from the Legacy AS 1.0 + * model in that it allows AS 2.0 style LinkValues + * to be used as the value of the options property. + * + * @author james + * + */ public class Question extends ASObject { public static final class Builder @@ -37,6 +49,12 @@ public class Question extends ASObject { objectType("question"); } + /** + * Add one or more answers to the question + * @param url String + * @param urls String[] optional vararg + * @return Builder + */ public Builder option(String url, String... urls) { if (url != null) link("options", url); @@ -46,6 +64,12 @@ public class Question extends ASObject { return this; } + /** + * Add one or more answers to the question + * @param url LinkValue + * @param urls LinkValue[] optional vararg + * @return Builder + */ public Builder option(LinkValue link, LinkValue... links) { if (link != null) link("options", link); @@ -55,10 +79,18 @@ public class Question extends ASObject { return this; } + /** + * Add an answer to the question + * @param link Supplier<? extends LinkValue> + * @return Builder + */ public Builder option(Supplier link) { return option(link.get()); } + /** + * Get the built question object + */ public Question get() { return new Question(this); } @@ -69,14 +101,25 @@ public class Question extends ASObject { super(builder); } + /** + * Get the list of options for the question + * @return Iterable<LinkValue> + */ public Iterable options() { return links("options"); } - + + /** + * Get the list of options for the question + * @param filter Predicate<? super LinkValue> + * @return Iterable<LinkValue> + */ public Iterable options(Predicate filter) { return links("options", filter); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Task.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Task.java index b258e2e..679f9c1 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Task.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/Task.java @@ -35,6 +35,12 @@ import com.google.common.base.Supplier; import com.ibm.common.activitystreams.ASObject; import com.ibm.common.activitystreams.LinkValue; +/** + * The Legacy "task" objectType. Task objects in AS 1.0 are essentially + * pending Activity statements. + * @author james + * + */ public class Task extends ASObject { @@ -45,22 +51,48 @@ public class Task objectType("task"); } + /** + * Set the actor + * @param actor ASObject + * @return Builder + */ public Builder actor(ASObject actor) { return set("actor", actor); } + /** + * Set the actor + * @param actor Supplier<? extends ASObject> + * @return Builder + */ public Builder actor(Supplier actor) { return actor(actor.get()); } + /** + * Set the object + * @param object ASObject + * @return Builder + */ public Builder object(ASObject object) { return set("object", object); } + /** + * Set the object + * @param object Supplier<? extends ASObject> + * @return Builder + */ public Builder object(Supplier object) { return object(object.get()); } + /** + * Set one or more prerequisite taskss + * @param task Task + * @param tasks Task[] optional vararg + * @return Builder + */ public Builder prerequisites(Task task, Task... tasks) { if (task != null) link("prerequisites",task); @@ -70,10 +102,33 @@ public class Task return this; } + /** + * Set one or more prerequisite tasks + * @param tasks Iterable<Task> + * @return Builder + */ + public Builder prerequisites(Iterable tasks) { + if (tasks != null) + for (Task task : tasks) + link("prerequisites", task); + return this; + } + + /** + * Set an optional prerequisite + * @param task Supplier<? extends Task> + * @return Builder + */ public Builder prerequisites(Supplier task) { return prerequisites(task.get()); } + /** + * Specify one or more other tasks that this task supersedes + * @param task Task + * @param tasks Task[] optional vararg + * @return Builder + */ public Builder supersedes(Task task, Task... tasks) { if (task != null) link("supersedes",task); @@ -83,46 +138,115 @@ public class Task return this; } + /** + * Specify one or more other tasks that this task supersedes + * @param tasks Iterable<Task> + * @return Builder + */ + public Builder supersedes(Iterable tasks) { + if (tasks != null) + for (Task task : tasks) + link("supersedes", task); + return this; + } + + /** + * Specify a task that this task supersedes + * @param task Supplier<? extends Task> + * @return Builder + */ public Builder supersedes(Supplier task) { return supersedes(task.get()); } + /** + * Indicates whether this task is required or not + * @param on boolean + * @return Builder + */ public Builder required(boolean on) { return set("required", on); } + /** + * Indicates that this task is required + * @return Builder + */ public Builder required() { return required(true); } + /** + * Specifies the verb for this task + * @param verb String + * @return Builder + */ public Builder verb(String verb) { return set("verb", verb); } + /** + * Specifies the due date for this task + * @param dt DateTime + * @return Builder + */ public Builder by(DateTime dt) { return this._dt("by", dt); } + /** + * Specifies that this task is due right now + * @return Builder + */ public Builder byNow() { return this._dtNow("by"); } + /** + * Specifies the due date for this task in terms of a specific + * duration of time from right now + * @param duration ReadableDuration + * @return Builder + */ public Builder byFromNow(ReadableDuration duration) { return this._dtFromNow("by", duration); } + /** + * Specifies the due date for this task in terms of a specific + * period of time from right now + * @param period ReadablePeriod + * @return Builder + */ public Builder byFromNow(ReadablePeriod period) { return this._dtFromNow("by", period); } + /** + * Specifies the due date for this task in terms of a specific + * duration of time from the given instant; + * @param dt DateTime + * @param duration ReadableDuration + * @return Builder + */ public Builder by(DateTime dt, ReadableDuration duration) { return this._dtFrom("by", dt, duration); } + /** + * Specifies the due date for this task in terms of a specific + * period of time from the given instant + * @param dt DateTime + * @param period ReadablePeriod + * @return Builder + */ public Builder by(DateTime dt, ReadablePeriod period) { return this._dtFrom("by", dt, period); } + /** + * Get the completed Task object + */ public Task get() { return new Task(this); } @@ -133,30 +257,62 @@ public class Task super(builder); } + /** + * Get the actor + * @return <A extends ASObject>A + */ public A actor() { return this.get("actor"); } + /** + * Get the object + * @return <A extends ASObject>A + */ public A object() { return this.get("object"); } + /** + * Get the due date + * @return DateTime + */ public DateTime by() { return getDateTime("by"); } + /** + * Get the verb + * @return String + */ public String verb() { return getString("verb"); } + /** + * Return true if this task is required + * @return boolean + */ public boolean required() { return getBoolean("required"); } + /** + * Return the listing of other tasks superseded by this one + * (will return an empty iterable if there are no superseded + * tasks) + * @return Iterable<Task> + */ public Iterable supersedes() { return transform(links("supersedes",filter), transformer); } + /** + * Return the listing of other tasks upon which this task depends. + * (will return an empty iterable if there are no prerequisite + * tasks) + * @return Iterable<Task> + */ public Iterable prerequisites() { return transform(links("prerequisites",filter), transformer); } @@ -176,6 +332,8 @@ public class Task }; + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); } diff --git a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/WithImage.java b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/WithImage.java index 724b13b..1d90428 100644 --- a/legacy/src/main/java/com/ibm/common/activitystreams/legacy/WithImage.java +++ b/legacy/src/main/java/com/ibm/common/activitystreams/legacy/WithImage.java @@ -26,15 +26,33 @@ import java.io.ObjectStreamException; import com.google.common.base.Supplier; import com.ibm.common.activitystreams.ASObject; +/** + * For the legacy "product" and "image" objectTypes. These + * include an additional "fullImage" property whose value + * is a MediaLink. + * + * @author james + * + */ public class WithImage extends ASObject { public static final class Builder extends ASObject.AbstractBuilder { + /** + * Set the fullImage property + * @param link MediaLink + * @return Builder + */ public Builder fullImage(MediaLink link) { return set("fullImage", link); } + /** + * Set the fullImage property + * @param link Supplier<? extends MediaLink> + * @return Builder + */ public Builder fullImage(Supplier link) { return fullImage(link.get()); } @@ -49,10 +67,16 @@ public class WithImage extends ASObject { super(builder); } + /** + * Get the fullImage property + * @return MediaLink + */ public MediaLink fullImage() { return this.get("fullImage"); } + // Java Serialization Support + Object writeReplace() throws java.io.ObjectStreamException { return new SerializedForm(this); }