Javadoc updates (#217)

* PLUGGED_IN and BATTERY_LEVEL properties are never null

* updated header

* moved fields for clarity of init order

* update references to Charm Down

* use Service.create() over Services.get()

* use Service.create() over Services.get()

* updated examples

* added a note to Android configuration that states Client plugin automatically takes care of modifications to manifest

* Remove link to javadoc for now

Co-authored-by: José Pereda <jperedadnr@gmail.com>
Co-authored-by: José Pereda <pereda@eii.uva.es>

modules/accelerometer/src/main/java/com/gluonhq/attach/accelerometer/AccelerometerService.java

@@ -44,8 +44,8 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(AccelerometerService.class).ifPresent(service -> {
- *      Acceleration acceleration = accelerometerService.getCurrentAcceleration();
+ * {@code AccelerometerService.create().ifPresent(service -> {
+ *      Acceleration acceleration = service.getCurrentAcceleration();
  *      System.out.printf("Current acceleration: %.2f, %.2f, %.2f",
  *              acceleration.getX(), acceleration.getY(), acceleration.getZ());
  *  });}</pre>

modules/audio-recording/src/main/java/com/gluonhq/attach/audiorecording/AudioRecordingService.java

@@ -59,7 +59,7 @@
  * 10 files of 1 minute duration each.</p>
  * 
  * <pre>
- * {@code Services.get(AudioRecordingService.class).ifPresent(audio -> {
+ * {@code AudioRecordingService.create().ifPresent(audio -> {
  *      audio.clearAudioFolder();
  *      audio.getAudioChunkFiles().addListener((ListChangeListener.Change<? extends String> c) -> {
  *          while (c.next()) {
@@ -80,6 +80,8 @@
  * <p><b>Android Configuration</b></p>
  * <p>The following <code>permission</code> and activity need to be added to the 
  * android manifest configuration file:</p>
+ *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest ...>
  *    ...

modules/audio/src/main/java/com/gluonhq/attach/audio/AudioService.java

@@ -35,6 +35,16 @@
 /**
  * The audio service provides access to loading native audio (sound and music) objects.
  *
+ * <p><b>Example</b></p>
+ * <pre>
+ * {@code AudioService.create().ifPresent(service -> {
+ *      service.loadSound(getClass().getResource("test.wav"))
+ *             .ifPresent(audio -> audio.play());
+ *  });}</pre>
+ *
+ * <p><b>Android Configuration</b>: none</p>
+ * <p><b>iOS Configuration</b>: none</p>
+ *
  * @author Almas Baimagambetov (almaslvl@gmail.com)
  * @since 4.0.9
  */

modules/augmented-reality/src/main/java/com/gluonhq/attach/augmentedreality/AugmentedRealityService.java

@@ -40,7 +40,7 @@
  * 
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(AugmentedRealityService.class).ifPresent(service -> {
+ * {@code AugmentedRealityService.create().ifPresent(service -> {
  *       Availability availability = service.checkAR(() -> {
  *          // perform action after ARCore is installed
  *       });
@@ -59,7 +59,7 @@
  * and {@code DukeKing.mtl} under the {@code src/main/resources/models} folder</p>
  * 
  * <pre>
- * {@code Services.get(AugmentedRealityService.class).ifPresent(service -> {
+ * {@code AugmentedRealityService.create().ifPresent(service -> {
  *       ARModel model = new ARModel();
  *       model.setName("DukeKing");
  *       model.setObjFilename("models/DukeKing.obj");
@@ -75,6 +75,8 @@
  *
  * <p><b>Android Configuration</b></p>
  * <p>Add the following to the manifest</p>
+ *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest ...>
  *   <uses-permission android:name="android.permission.CAMERA" />

modules/barcode-scan/src/main/java/com/gluonhq/attach/barcodescan/BarcodeScanService.java

@@ -39,7 +39,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(BarcodeScanService.class).ifPresent(service -> {
+ * {@code BarcodeScanService.create().ifPresent(service -> {
  *      Optional<String> barcode = barcodeScanService.scan();
  *      barcode.ifPresent(barcodeValue -> System.out.println("Scanned Bar Code: " + barcodeValue));
  *  });}</pre>
@@ -48,6 +48,8 @@
  * <p>The permission <code>android.permission.CAMERA</code> needs to be added together
  * with the following <code>activity</code> configuration that handles the SCAN intent
  * of the BarcodeScanService.</p>
+ *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest ...>
  *    <uses-permission android:name="android.permission.CAMERA"/>

modules/battery/src/main/java/com/gluonhq/attach/battery/BatteryService.java

@@ -39,7 +39,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(BatteryService.class).ifPresent(service -> {
+ * {@code BatteryService.create().ifPresent(service -> {
  *      float batteryLevel = service.getBatteryLevel();
  *      boolean pluggedIn = service.isPluggedIn();
  *  });}</pre>

modules/ble/src/main/java/com/gluonhq/attach/ble/BleService.java

@@ -47,7 +47,7 @@
  * <p><b>Example</b></p>
  * <pre>
  * {@code String uuid = UUID.randomUUID().toString(); // for example a known UUID of a beacon
- *  Services.get(BleService.class).ifPresent(service -> {
+ *  BleService.create().ifPresent(service -> {
  *      service.startScanning(new Configuration(uuid), scanResult -> {
  *          System.out.printf("major: %d, minor: %d, proximity: %s",
  *                  scanResult.getMajor(), scanResult.getMinor(),
@@ -94,7 +94,7 @@
  * <p>This code snippet shows how to discover devices:</p>
  * <pre>
  * {@code
- * Services.get(BleService.class).ifPresent(ble -> {
+ * BleService.create().ifPresent(ble -> {
  *        ble.startScanningDevices().addListener((ListChangeListener.Change<? extends BleDevice> c) -> {
  *            while (c.next()) {
  *                if (c.wasAdded()) {
@@ -116,7 +116,7 @@
  * <p>This code snippet shows how to discover the services for a given device:</p>
  * <pre>
  * {@code
- * Services.get(BleService.class).ifPresent(ble -> {
+ * BleService.create().ifPresent(ble -> {
  *        ...
  *        bleDevice.getProfiles().addListener((ListChangeListener.Change<? extends BleProfile> c) -> {
  *            while (c.next()) {
@@ -135,7 +135,7 @@
  * <p>This code snippet shows how to discover the characteristics for a given service:</p>
  * <pre>
  * {@code
- * Services.get(BleService.class).ifPresent(ble -> {
+ * BleService.create().ifPresent(ble -> {
  *        ...
  *        bleProfile.getCharacteristics().addListener((ListChangeListener.Change<? extends BleCharacteristic> c) -> {
  *            while (c.next()) {
@@ -154,7 +154,7 @@
  * <p>And finally, this code snippet shows how to subscribe to a characteristic of a given device and service to listen to its values:</p>
  * <pre>
  * {@code
- * Services.get(BleService.class).ifPresent(ble -> {
+ * BleService.create().ifPresent(ble -> {
  *        ...
  *        bleCharacteristic.valueProperty().addListener((obs, ov, nv) ->
  *              System.out.println("Value: " + Arrays.toString(nv)));
@@ -168,13 +168,14 @@
  * <code>android.permission.BLUETOOTH_ADMIN</code> and
  * <code>android.permission.ACCESS_FINE_LOCATION</code> need to be added to the Android manifest.</p>
  *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest ...>
  *    <uses-permission android:name="android.permission.BLUETOOTH"/>
  *    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
  *    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  *    ...
- *    <activity android:name="com.gluonhq.impl.charm.down.plugins.android.PermissionRequestActivity" />
+ *    <activity android:name="com.gluonhq.helloandroid.PermissionRequestActivity" />
  *  </manifest>}</pre>
  *
  * <p><b>iOS Configuration</b></p>

modules/browser/src/main/java/com/gluonhq/attach/browser/BrowserService.java

@@ -39,7 +39,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(BrowserService.class).ifPresent(service -> {
+ * {@code BrowserService.create().ifPresent(service -> {
  *      service.launchExternalBrowser("https://gluonhq.com/");
  *  });}</pre>
  *

modules/cache/src/main/java/com/gluonhq/attach/cache/CacheService.java

@@ -38,7 +38,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(CacheService.class).ifPresent(service -> {
+ * {@code CacheService.create().ifPresent(service -> {
  *      Cache<String, String> cache = service.getCache("simpleCache");
  *      cache.put("key", "value");
  *      String value = cache.get("key");

modules/compass/src/main/java/com/gluonhq/attach/compass/CompassService.java

@@ -44,7 +44,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(CompassService.class).ifPresent(service -> {
+ * {@code CompassService.create().ifPresent(service -> {
  *      double heading = service.getHeading();
  *      System.out.printf("Current heading: %.2f", heading);
  *  });}</pre>

modules/connectivity/src/main/java/com/gluonhq/attach/connectivity/ConnectivityService.java

@@ -45,13 +45,15 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(ConnectivityService.class).ifPresent(service -> {
+ * {@code ConnectivityService.create().ifPresent(service -> {
  *      boolean connected = service.isConnected();
  *      System.out.println("Network connectivity available? " + String.valueOf(connected));
  *  });}</pre>
  *
  * <p><b>Android Configuration</b></p>
  * <p>The permission <code>android.permission.ACCESS_NETWORK_STATE</code> needs to be added.</p>
+ *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest ...>
  *    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

modules/device/src/main/java/com/gluonhq/attach/device/DeviceService.java

@@ -36,7 +36,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(DeviceService.class).ifPresent(service -> {
+ * {@code DeviceService.create().ifPresent(service -> {
  *      System.out.printf("Device Model Name: %s", service.getModel());
  *  });}</pre>
  *

modules/dialer/src/main/java/com/gluonhq/attach/dialer/DialerService.java

@@ -37,12 +37,14 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(DialerService.class).ifPresent(service -> {
+ * {@code DialerService.create().ifPresent(service -> {
  *      service.call("+32987123456");
  *  });}</pre>
  *
  * <p><b>Android Configuration</b></p>
  * <p>The permission <code>android.permission.CALL_PHONE</code> needs to be added.</p>
+ *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest ...>
  *    <uses-permission android:name="android.permission.CALL_PHONE"/>

modules/display/src/main/java/com/gluonhq/attach/display/DisplayService.java

@@ -40,7 +40,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(DisplayService.class).ifPresent(service -> {
+ * {@code DisplayService.create().ifPresent(service -> {
  * 　　  Dimension2D resolution = service.getScreenResolution();
  *      System.out.printf("Screen resolution: %.0fx%.0f", resolution.getWidth(), resolution.getHeight());
  *  });}</pre>

modules/in-app-billing/src/main/java/com/gluonhq/attach/inappbilling/InAppBillingService.java

@@ -47,7 +47,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code InAppBillingService service = Services.get(InAppBillingService.class)
+ * {@code InAppBillingService service = InAppBillingService.create()
  *          .orElseThrow(() -> new RuntimeException("Could not load In-App Billing service"));
  *
  *      // initialize and register available products
@@ -97,6 +97,8 @@
  *
  * <p><b>Android Configuration</b></p>
  * <p>The permission <code>com.android.vending.BILLING</code> needs to be added.</p>
+ *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest ...>
  *    <uses-permission android:name="com.android.vending.BILLING"/>

modules/keyboard/src/main/java/com/gluonhq/attach/keyboard/KeyboardService.java

@@ -40,7 +40,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(KeyboardService.class).ifPresent(service -> {
+ * {@code KeyboardService.create().ifPresent(service -> {
  *      service.visibleHeightProperty().addListener((obs, ov, nv) ->
  *          System.out.println("height: " + nv));
  *  });}</pre>

modules/lifecycle/src/main/java/com/gluonhq/attach/lifecycle/LifecycleService.java

@@ -38,7 +38,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(LifecycleService.class).ifPresent(service -> {
+ * {@code LifecycleService.create().ifPresent(service -> {
  *      service.addListener(LifecycleEvent.PAUSE, () -> System.out.println("Application is paused."));
  *      service.addListener(LifecycleEvent.RESUME, () -> System.out.println("Application is resumed."));
  *  });}</pre>

modules/local-notifications/src/main/java/com/gluonhq/attach/localnotifications/LocalNotificationsService.java

@@ -66,7 +66,7 @@
  * <p><b>Example</b></p>
  * <pre>
  * {@code String notificationId = "abcd1234";
- *  Services.get(LocalNotificationsService.class).ifPresent(service -> {
+ *  LocalNotificationsService.create().ifPresent(service -> {
  *      service.getNotifications().add(new Notification(notificationId, "Sample Notification Text",
  *              ZonedDateTime.now().plusSeconds(20), () -> {
  *                      Alert alert = new Alert(AlertType.INFORMATION, "You have been notified!");
@@ -78,6 +78,8 @@
  * <p>The following <code>activity</code> and <code>receiver</code> need to be added to the android manifest
  * configuration file to make local notifications work on android. The main activity also requires the attribute
  * <code>android:launchMode</code> with value <code>singleTop</code>.</p>
+ *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest ...>
  *    ...

modules/magnetometer/src/main/java/com/gluonhq/attach/magnetometer/MagnetometerService.java

@@ -47,7 +47,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(MagnetometerService.class).ifPresent(service -> {
+ * {@code MagnetometerService.create().ifPresent(service -> {
  *      service.start();
  *      MagnetometerReading reading = service.getReading();
  *      System.out.printf("Magnetic field: %.4f, %.4f, %.4f. Magnitude: %.4f",

modules/orientation/src/main/java/com/gluonhq/attach/orientation/OrientationService.java

@@ -45,7 +45,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(OrientationService.class).ifPresent(service -> {
+ * {@code OrientationService.create().ifPresent(service -> {
  *      Orientation orientation = service.getOrientation();
  *      System.out.println("Current orientation: " + orientation.name());
  *  });}</pre>

modules/pictures/src/main/java/com/gluonhq/attach/pictures/PicturesService.java

@@ -40,7 +40,7 @@
  * <p><b>Example</b></p>
  * <pre>
  * {@code ImageView imageView = new ImageView();
- *  Services.get(PicturesService.class).ifPresent(service -> {
+ *  PicturesService.create().ifPresent(service -> {
  *      service.takePhoto(false).ifPresent(image -> imageView.setImage(image));
  *  });}</pre>
  *
@@ -50,10 +50,10 @@
  * <p><b>Example</b></p>
  * <pre>
  * {@code ImageView imageView = new ImageView();
- *  Services.get(PicturesService.class).ifPresent(service -> {
+ *  PicturesService.create().ifPresent(service -> {
  *      service.loadFromGallery().ifPresent(image -> imageView.setImage(image));
  *      service.getImageFile().ifPresent(file ->
- *          Services.get(ShareService.class).ifPresent(share ->
+ *          ShareService.create().ifPresent(share ->
  *              share.share("image/jpeg", file)));
  *  });}</pre>
  *
@@ -73,6 +73,8 @@
  * <p>The permission <code>android.permission.CAMERA</code> needs to be added as well as the permissions
  * <code>android.permission.READ_EXTERNAL_STORAGE</code> and <code>android.permission.WRITE_EXTERNAL_STORAGE</code>
  * to be able to read and write images. Also a {@code provider} is required:</p>
+ *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest package="${application.package.name}" ...>
  *    <uses-permission android:name="android.permission.CAMERA"/>

modules/position/src/main/java/com/gluonhq/attach/position/PositionService.java

@@ -54,7 +54,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(PositionService.class).ifPresent(service -> {
+ * {@code PositionService.create().ifPresent(service -> {
  *      service.positionProperty().addListener((obs, ov, nv) ->
  *          System.out.printf("Current position: %.5f, %.5f",
  *              nv.getLatitude(), nv.getLongitude()));
@@ -69,7 +69,8 @@
  * <p>For background updates, the service <code>positionBackgroundService</code>
  * has to be included as well. Note that in this mode the accuracy could be reduced
  * by the system.</p>
-
+ *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
  * <pre>
  * {@code <manifest ...>
  *    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

modules/position/src/main/native/android/dalvik/DalvikPositionService.java

@@ -187,7 +187,7 @@ private void initialize() {
         final Intent serviceIntent = new Intent(activityContext, AndroidPositionBackgroundService.class);
         final IntentFilter intentFilter = new IntentFilter(AndroidPositionBackgroundService.class.getName());
         
-        Services.get(LifecycleService.class).ifPresent(l -> {
+        LifecycleService.create().ifPresent(l -> {
             l.addListener(LifecycleEvent.PAUSE, () -> {
                 quitLooperTask();
                 // if the PositionService is still running and backgroundModeEnabled 

modules/runtime-args/src/main/java/com/gluonhq/attach/runtimeargs/RuntimeArgsService.java

@@ -51,6 +51,8 @@
  * To launch the app from a custom URL, like yourScheme://foo.html, register a
  * custom scheme in the AndroidManifest.xml file:
  *
+ * Note: these modifications are handled automatically by <a href="https://docs.gluonhq.com/client">Client plugin</a> if it is used.
+ *
  * {@code
     <activity android:name="com.gluonhq.helloandroid.LaunchURLActivity"
             android:launchMode="singleTask"

modules/settings/src/main/java/com/gluonhq/attach/settings/SettingsService.java

@@ -37,7 +37,7 @@
  *
  * <p><b>Example</b></p>
  * <pre>
- * {@code Services.get(SettingsService.class).ifPresent(service -> {
+ * {@code SettingsService.create().ifPresent(service -> {
  *      service.store("key", "value");
  *      String value = service.retrieve("key");
  *      service.remove("key");