add javadocs

Author: sammefford

src/main/java/com/marklogic/client/pojo/annotation/GeospatialLatitude.java

@@ -18,6 +18,60 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/** Use this annotation in combination with {@link GeospatialLongitude} on a
+ * sibling property to specify that a Geospatial Element Pair Index should
+ * be created for these pojo properties. The value should follow the rules
+ * for any Geospatial Element Pair Index in MarkLogic Server with coordinate
+ * system "wgs84".
+ *
+ * This annotation can be associated with a public field:
+ * <pre>    import com.marklogic.client.pojo.annotation.GeospatialLatitude;
+ *    import com.marklogic.client.pojo.annotation.GeospatialLongitude;
+ *    public class MyClass {
+ *      <b>{@literal @}GeospatialLatitude</b>
+ *      public String latitude;
+ *      {@literal @}GeospatialLongitude
+ *      public String longitude;
+ *    }</pre>
+ *
+ * or with a public getter method:
+ * <pre>
+ *    public class MyClass {
+ *      private String latitude;
+ *      private String longitude;
+ *      <b>{@literal @}GeospatialLatitude</b>
+ *      public String getLatitude() {
+ *        return latitude;
+ *      }
+ *      {@literal @}GeospatialLongitude
+ *      public String getLongitude() {
+ *        return longitude;
+ *      }
+ *      // ... setter methods ...
+ *    }</pre>
+*
+ * or with a public setter method:
+ * <pre>
+ *    public class MyClass {
+ *      private String latitude;
+ *      private String longitude;
+ *
+ *      // ... getter methods ...
+ *
+ *      <b>{@literal @}GeospatialLatitude</b>
+ *      public void setLatitude(String latitude) {
+ *        this.latitude = latitude;
+ *      }
+ *      {@literal @}GeospatialLongitude
+ *      public void setLongitude(String longitude) {
+ *        this.longitude = longitude;
+ *      }
+ *    }</pre>
+ * Run
+ * {@link com.marklogic.client.pojo.util.GenerateIndexConfig} to generate
+ * a package that can be used by administrators to create the indexes in
+ * MarkLogic Server.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface GeospatialLatitude {
 }

src/main/java/com/marklogic/client/pojo/annotation/GeospatialLongitude.java

@@ -18,6 +18,60 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/** Use this annotation in combination with {@link GeospatialLatitude} on a
+ * sibling property to specify that a Geospatial Element Pair Index should
+ * be created for these pojo properties. The value should follow the rules
+ * for any Geospatial Element Pair Index in MarkLogic Server with coordinate
+ * system "wgs84".
+ *
+ * This annotation can be associated with a public field:
+ * <pre>    import com.marklogic.client.pojo.annotation.GeospatialLatitude;
+ *    import com.marklogic.client.pojo.annotation.GeospatialLongitude;
+ *    public class MyClass {
+ *      {@literal @}GeospatialLatitude
+ *      public String latitude;
+ *      <b>{@literal @}GeospatialLongitude</b>
+ *      public String longitude;
+ *    }</pre>
+ *
+ * or with a public getter method:
+ * <pre>
+ *    public class MyClass {
+ *      private String latitude;
+ *      private String longitude;
+ *      {@literal @}GeospatialLatitude
+ *      public String getLatitude() {
+ *        return latitude;
+ *      }
+ *      <b>{@literal @}GeospatialLongitude</b>
+ *      public String getLongitude() {
+ *        return longitude;
+ *      }
+ *      // ... setter methods ...
+ *    }</pre>
+*
+ * or with a public setter method:
+ * <pre>
+ *    public class MyClass {
+ *      private String latitude;
+ *      private String longitude;
+ *
+ *      // ... getter methods ...
+ *
+ *      {@literal @}GeospatialLatitude
+ *      public void setLatitude(String latitude) {
+ *        this.latitude = latitude;
+ *      }
+ *      <b>{@literal @}GeospatialLongitude</b>
+ *      public void setLongitude(String longitude) {
+ *        this.longitude = longitude;
+ *      }
+ *    }</pre>
+ * Run
+ * {@link com.marklogic.client.pojo.util.GenerateIndexConfig} to generate
+ * a package that can be used by administrators to create the indexes in
+ * MarkLogic Server.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface GeospatialLongitude {
 }

src/main/java/com/marklogic/client/pojo/annotation/GeospatialPathIndexProperty.java

@@ -18,6 +18,46 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/** Use this annotation to specify that a Geospatial Path Index should
+ * be created for this pojo property. The value should follow the rules
+ * for any Geospatial Path Index in MarkLogic Server with coordinate
+ * system "wgs84" and point format "point". Specifically, the value 
+ * should be in "{latititude} {longitude}" point format where {latitude}
+ * and {longitude} are numeric geospatial wgs84 position values.
+ *
+ * This annotation can be associated with a public field:
+ * <pre>    import com.marklogic.client.pojo.annotation.GeospatialPathIndexProperty;
+ *    public class MyClass {
+ *      <b>{@literal @}GeospatialPathIndexProperty</b>
+ *      public String myGeoProperty;
+ *    }</pre>
+ *
+ * or with a public getter method:
+ * <pre>
+ *    public class MyClass {
+ *      private String myGeoProperty;
+ *      <b>{@literal @}GeospatialPathIndexProperty</b>
+ *      public String getMyGeoProperty() {
+ *        return myGeoProperty;
+ *      }
+ *      // ... setter methods ...
+ *    }</pre>
+*
+ * or with a public setter method:
+ * <pre>
+ *    public class MyClass {
+ *      private String myGeoProperty;
+ *      // ... getter methods ...
+ *      <b>{@literal @}GeospatialPathIndexProperty</b>
+ *      public void setMyGeoProperty(String myGeoProperty) {
+ *        this.myGeoProperty = myGeoProperty;
+ *      }
+ *    }</pre>
+ * Run
+ * {@link com.marklogic.client.pojo.util.GenerateIndexConfig} to generate
+ * a package that can be used by administrators to create the indexes in
+ * MarkLogic Server.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface GeospatialPathIndexProperty {
 }

src/main/java/com/marklogic/client/pojo/annotation/Id.java

@@ -17,7 +17,52 @@
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import com.marklogic.client.pojo.PojoRepository;
 
+/** Use this annotation to specify the Id property for each pojo class.
+ * To work properly with {@link PojoRepository#write PojoRepository.write},
+ * each pojo class must have one and only one property annotated with
+ * the Id annotation. The property annotated with Id is used to 
+ * generate a unique URI in MarkLogic Server
+ * for each persisted instance, and thus should be a property with a
+ * unique value for each instance.  <br><br>
+ *
+ * This annotation can be associated with a public field:
+ * <pre>    import com.marklogic.client.pojo.annotation.Id;
+ *    public class MyClass {
+ *      <b>{@literal @}Id</b>
+ *      public Long myId;
+ *    }</pre>
+ *
+ * or with a public getter method:
+ * <pre>
+ *    public class MyClass {
+ *      private Long myId;
+ *      <b>{@literal @}Id</b>
+ *      public Long getMyId() {
+ *        return myId;
+ *      }
+ *      // ... setter methods ...
+ *    }</pre>
+*
+ * or with a public setter method:
+ * <pre>
+ *    public class MyClass {
+ *      private Long myId;
+ *
+ *      // ... getter methods ...
+ *
+ *      <b>{@literal @}Id</b>
+ *      public void setMyId(Long myId) {
+ *        this.myId = myId;
+ *      }
+ *    }</pre>
+ *
+ * This annotation is used only at
+ * runtime to generate unique uris, so there is no need to run
+ * {@link com.marklogic.client.pojo.util.GenerateIndexConfig} to do
+ * anything with this annotation.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Id {
 }

src/main/java/com/marklogic/client/pojo/annotation/PathIndexProperty.java

@@ -18,6 +18,49 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/** Use this annotation to specify that a Path Index (required for range
+ * queries) should be created for this pojo property.  A path index is
+ * used rather than an element range index because we can restrict matches
+ * to only properties that are direct children of this class type.  We
+ * do this by including the class name in the path specification on the
+ * path index.
+ *
+ * This annotation can be associated with a public field:
+ * <pre>    import com.marklogic.client.pojo.annotation.PathIndexProperty;
+ *    public class MyClass {
+ *      <b>{@literal @}PathIndexProperty</b>
+ *      public Long myLongValue;
+ *    }</pre>
+ *
+ * or with a public getter method:
+ * <pre>
+ *    public class MyClass {
+ *      private Long myLongValue;
+ *      <b>{@literal @}PathIndexProperty</b>
+ *      public Long getMyLongValue() {
+ *        return myLongValue;
+ *      }
+ *      // ... setter methods ...
+ *    }</pre>
+*
+ * or with a public setter method:
+ * <pre>
+ *    public class MyClass {
+ *      private Long myLongValue;
+ *
+ *      // ... getter methods ...
+ *
+ *      <b>{@literal @}PathIndexProperty</b>
+ *      public void setMyLongValue(Long myLongValue) {
+ *        this.myLongValue = myLongValue;
+ *      }
+ *    }</pre>
+ * Run
+ * {@link com.marklogic.client.pojo.util.GenerateIndexConfig} to generate
+ * a package that can be used by administrators to create the indexes in
+ * MarkLogic Server.
+ * @see com.marklogic.client.pojo.PojoQueryBuilder#range
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface PathIndexProperty {
     ScalarType scalarType();