1.1 --- a/geo/pom.xml Sun Jul 07 07:47:58 2013 +0200
1.2 +++ b/geo/pom.xml Sun Jul 07 08:31:14 2013 +0200
1.3 @@ -15,6 +15,18 @@
1.4 <properties>
1.5 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
1.6 </properties>
1.7 + <build>
1.8 + <plugins>
1.9 + <plugin>
1.10 + <groupId>org.apache.maven.plugins</groupId>
1.11 + <artifactId>maven-javadoc-plugin</artifactId>
1.12 + <configuration>
1.13 + <subpackages>net.java.html.geo</subpackages>
1.14 + <skip>false</skip>
1.15 + </configuration>
1.16 + </plugin>
1.17 + </plugins>
1.18 + </build>
1.19 <dependencies>
1.20 <dependency>
1.21 <groupId>org.testng</groupId>
2.1 --- a/geo/src/main/java/net/java/html/geo/OnLocation.java Sun Jul 07 07:47:58 2013 +0200
2.2 +++ b/geo/src/main/java/net/java/html/geo/OnLocation.java Sun Jul 07 08:31:14 2013 +0200
2.3 @@ -25,14 +25,49 @@
2.4 import java.lang.annotation.RetentionPolicy;
2.5 import java.lang.annotation.Target;
2.6
2.7 -/**
2.8 +/** Generates a handle which can configure, {@link Position.Handle#start() start}
2.9 + * and {@link Position.Handle#stop() stop} requests for obtaining current
2.10 + * location of the application/device/user. Put the {@link OnLocation} annotation
2.11 + * on top of a (non-private) method in your class which takes one argument
2.12 + * {@link Position}. Based on name of your method (unless a class name is
2.13 + * directly specified via {@link #className()} attribute) a handle class is
2.14 + * generated. For example if your method name is <code>callMeWhenYouKnowWhereYouAre</code>
2.15 + * a package private class <code>CallMeWhenYouKnowWhereYouAreHandle</code> will
2.16 + * be generated in the same package. One can use its <code>createQuery</code>
2.17 + * and <code>createWatch</code> static method to get one time/repeated time
2.18 + * instance of a {@link Position.Handle handle}. After configuring the
2.19 + * {@link Position.Handle handle} via its setter methods, one can
2.20 + * {@link Position.Handle#start() start} the location request.
2.21 + * <p>
2.22 + * In case something goes wrong a method in the same class named {@link #onError()}
2.23 + * can be specified (should take one {@link Exception} parameter).
2.24 + * <p>
2.25 + * The overall behavior of the system mimics <a href="http://www.w3.org/TR/2012/PRgeolocationAPI20120510/">
2.26 + * W3C's Geolocation API</a>.
2.27 *
2.28 * @author Jaroslav Tulach <jtulach@netbeans.org>
2.29 */
2.30 @Retention(RetentionPolicy.SOURCE)
2.31 @Target(ElementType.METHOD)
2.32 public @interface OnLocation {
2.33 + /** Name of the {@link Position.Handle handle} class to generate. By
2.34 + * default the name is derived from the name of annotated method by
2.35 + * capitalizing the first character and appending <code>Handle</code>.
2.36 + * <p>
2.37 + * The generated class contains two static methods: <code>createQuery</code>
2.38 + * and <code>createWatch</code> which take no parameters if this method
2.39 + * is static or one parameter (of this class) if this method is instance
2.40 + * one. Both static methods return {@link Position.Handle}.
2.41 + *
2.42 + * @return string suitable for a new class in the same package
2.43 + */
2.44 public String className() default "";
2.45
2.46 + /** Name of a method in this class which should be called in case of
2.47 + * an error. The method has to be non-private and take {@link Exception}
2.48 + * parameter. By default the exception printed to console.
2.49 + *
2.50 + * @return name of method in this class
2.51 + */
2.52 public String onError() default "";
2.53 }
3.1 --- a/geo/src/main/java/net/java/html/geo/Position.java Sun Jul 07 07:47:58 2013 +0200
3.2 +++ b/geo/src/main/java/net/java/html/geo/Position.java Sun Jul 07 08:31:14 2013 +0200
3.3 @@ -47,8 +47,10 @@
3.4 private Double speed;
3.5 }
3.6
3.7 - /**
3.8 - *
3.9 + /** Rather than subclassing this class directly consider using {@link OnLocation}
3.10 + * annotation. Such annotation will generate a subclass for you automatically
3.11 + * with two static methods <code>createQuery</code> and <code>createWatch</code>
3.12 + * which can be used to obtain instance of this class.
3.13 */
3.14 public static abstract class Handle {
3.15
3.16 @@ -57,30 +59,63 @@
3.17 private long timeout;
3.18 private long maximumAge;
3.19
3.20 + /** Creates new instance of this handle.
3.21 + *
3.22 + * @param oneTime <code>true</code> if the handle represents one time
3.23 + * <em>query</em>. <code>false</code> if it represents a <em>watch</em>
3.24 + */
3.25 protected Handle(boolean oneTime) {
3.26 super();
3.27 this.oneTime = oneTime;
3.28 }
3.29
3.30 + /** Callback from the implementation when a (new) position has been
3.31 + * received and identified
3.32 + * @param p the position
3.33 + * @throws Throwable if an exception is thrown, it will be logged by the system
3.34 + */
3.35 protected abstract void onLocation(Position p) throws Throwable;
3.36
3.37 - protected abstract void onError(Throwable t) throws Throwable;
3.38 + /** Callback when an error occurs.
3.39 + * @param ex the exception describing what went wrong
3.40 + * @throws Throwable if an exception is thrown, it will be logged by the system
3.41 + */
3.42 + protected abstract void onError(Exception ex) throws Throwable;
3.43
3.44 + /** Turns on high accuracy mode as specified by the
3.45 + * <a href="http://www.w3.org/TR/2012/PRgeolocationAPI20120510/">
3.46 + * W3C's Geolocation API</a>. By default the mode is disabled.
3.47 + * @param enable <code>true</code> or <code>false</code>
3.48 + */
3.49 public void setHighAccuracy(boolean enable) {
3.50 this.enableHighAccuracy = enable;
3.51 }
3.52
3.53 + /** The amount of milliseconds to wait for a result.
3.54 + * By default infinity.
3.55 + * @param timeout time in milliseconds to wait for a result.
3.56 + */
3.57 public void setTimeout(long timeout) {
3.58 this.timeout = timeout;
3.59 }
3.60
3.61 + /** Sets maximum age of cached results which are acceptable to be
3.62 + * returned. By default maximum age is set to zero.
3.63 + * @param age time in milliseconds of acceptable cached results
3.64 + */
3.65 public void setMaximumAge(long age) {
3.66 this.maximumAge = age;
3.67 }
3.68
3.69 + /** Initializes the <em>query</em> or <em>watch</em> request(s) and
3.70 + * returns immediately.
3.71 + */
3.72 public void start() {
3.73 }
3.74
3.75 + /** Stops all pending requests. After this call no further callbacks
3.76 + * can be obtained.
3.77 + */
3.78 public void stop() {
3.79 }
3.80 }
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/geo/src/main/java/net/java/html/geo/package.html Sun Jul 07 08:31:14 2013 +0200
4.3 @@ -0,0 +1,37 @@
4.4 +<!--
4.5 +
4.6 + HTML via Java(tm) Language Bindings
4.7 + Copyright (C) 2013 Jaroslav Tulach <jaroslav.tulach@apidesign.org>
4.8 +
4.9 + This program is free software: you can redistribute it and/or modify
4.10 + it under the terms of the GNU General Public License as published by
4.11 + the Free Software Foundation, version 2 of the License.
4.12 +
4.13 + This program is distributed in the hope that it will be useful,
4.14 + but WITHOUT ANY WARRANTY; without even the implied warranty of
4.15 + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4.16 + GNU General Public License for more details. apidesign.org
4.17 + designates this particular file as subject to the
4.18 + "Classpath" exception as provided by apidesign.org
4.19 + in the License file that accompanied this code.
4.20 +
4.21 + You should have received a copy of the GNU General Public License
4.22 + along with this program. Look for COPYING file in the top folder.
4.23 + If not, see http://wiki.apidesign.org/wiki/GPLwithClassPathException
4.24 +
4.25 +-->
4.26 +<!DOCTYPE html>
4.27 +<html>
4.28 + <head>
4.29 + <title>Geolocation API for Java</title>
4.30 + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
4.31 + <meta name="viewport" content="width=device-width">
4.32 + </head>
4.33 + <body>
4.34 + <div>
4.35 + HTML Geo API for Java provides <a href="OnLocation.html">annotation based way</a> of
4.36 + obtaining geolocation information from a browser or any other
4.37 + device capable of providing it.
4.38 + </div>
4.39 + </body>
4.40 +</html>