params.json

{
  "name": "JDeferred",
  "tagline": "Java Deferred / Promise library",
  "body": "<!--\r\n  Copyright 2013 Ray Tsang\r\n  \r\n  Licensed under the Apache License, Version 2.0 (the \"License\");\r\n  you may not use this file except in compliance with the License.\r\n  You may obtain a copy of the License at\r\n  \r\n    http://www.apache.org/licenses/LICENSE-2.0\r\n  \r\n  Unless required by applicable law or agreed to in writing, software\r\n  distributed under the License is distributed on an \"AS IS\" BASIS,\r\n  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r\n  See the License for the specific language governing permissions and\r\n  limitations under the License.\r\n-->\r\n\r\nJDeferred\r\n=========\r\n\r\nJDeferred is a Java Deferred/Promise library similar to JQuery's Deferred Object.\r\n\r\nInspired by [JQuery](https://github.com/jquery/jquery) and [Android Deferred Object](https://github.com/CodeAndMagic/android-deferred-object).\r\n\r\n<a name=\"features\"></a>Features\r\n--------\r\n* Deferred object and Promise\r\n* Promise callbacks\r\n  * ```.then(…)```\r\n  * ```.done(…)```\r\n  * ```.fail(…)```\r\n  * ```.progress(…)```\r\n  * ```.always(…)```\r\n* Multiple promises\r\n  * ```.when(p1, p2, p3, …).then(…)```\r\n* Callable and Runnable wrappers\r\n  * ```.when(new Runnable() {…})```\r\n* Uses Executor Service\r\n* Java Generics support\r\n  * ```Deferred<Integer, Exception, Double> deferred;```\r\n  * ```deferred.resolve(10);```\r\n  * ```deferred.reject(new Exception());```\r\n  * ```deferred.notify(0.80);```\r\n* Android Support\r\n* Java 8 Lambda friendly\r\n* Yes it's on Maven Central Repository!\r\n\r\nMaven\r\n-----\r\n```xml\r\n<dependency>\r\n    <groupId>org.jdeferred</groupId>\r\n    <artifactId>jdeferred-core</artifactId>\r\n    <version>${version}</version>\r\n</dependency>\r\n```\r\n\r\nGradle\r\n-----\r\n```\r\ncompile 'org.jdeferred:jdeferred-android-aar:${version}'\r\n// or\r\ncompile 'org.jdeferred:jdeferred-android-aar:${version}@aar'\r\n```\r\n\r\nFind available versions on [Maven Central Repository](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.jdeferred%22%20AND%20a%3A%22jdeferred-core%22).\r\n\r\n<a name=\"examples\"></a>Quick Examples\r\n==============\r\n\r\n<a name=\"examples-deferred-promise\"></a>Deferred object and Promise\r\n---------------------------\r\n\r\n```java\r\nDeferred deferred = new DeferredObject();\r\nPromise promise = deferred.promise();\r\npromise.done(new DoneCallback() {\r\n  public void onDone(Object result) {\r\n    ...\r\n  }\r\n}).fail(new FailCallback() {\r\n  public void onFail(Object rejection) {\r\n    ...\r\n  }\r\n}).progress(new ProgressCallback() {\r\n  public void onProgress(Object progress) {\r\n    ...\r\n  }\r\n}).always(new AlwaysCallback() {\r\n  public void onAlways(State state, Object result, Object rejection) {\r\n    ...\r\n  }\r\n});\r\n```\r\nWith the reference to deferred object, you can then trigger actions/updates:\r\n\r\n```java\r\ndeferred.resolve(\"done\");\r\ndeferred.reject(\"oops\");\r\ndeferred.notify(\"100%\");\r\n```\r\n\r\n<a name=\"example-filter\"></a>Filter\r\n-----------\r\n```java\r\nDeferred d = …;\r\nPromise p = d.promise();\r\nPromise filtered = p.then(new DoneFilter<Integer, Integer>() {\r\n  public Integer filterDone(Integer result)\r\n    return result * 10;\r\n  }\r\n});\r\n\r\nfiltered.done(new DoneCallback<Integer>() {\r\n  public void onDone(Integer result) {\r\n    // result would be original * 10\r\n    System.out.println(result);\r\n  }\r\n});\r\n\r\nd.resolve(3) -> 30.\r\n```\r\n\r\n<a name=\"example-pipe\"></a>Pipe\r\n----\r\n> Since 1.1.0-Beta1\r\n\r\n```java\r\nDeferred d = ...;\r\nPromise p = d.promise();\r\n\r\np.then(new DonePipe<Integer, Integer, Exception, Void>() {\r\n  public Deferred<Integer, Exception, Void> pipeDone(Integer result) {\r\n    if (result < 100) {\r\n      return new DeferredObject<Integer, Void, Void>().resolve(result);\r\n    } else {\r\n      return new DeferredObject<Integer, Void, Void>().reject(new Exception(...));\r\n    }\r\n  }\r\n}).done(...).fail(...);\r\n\r\nd.resolve(80) -> done!\r\nd.resolve(100) -> fail!\r\n\r\n```\r\n\r\n<a name=\"example-dm\"></a>Deferred Manager\r\n----------------\r\n```java\r\nDeferredManager dm = new DefaultDeferredManager();\r\nPromise p1, p2, p3;\r\n// initialize p1, p2, p3\r\ndm.when(p1, p2, p3)\r\n  .done(…)\r\n  .fail(…)\r\n```\r\nYou can also specify a Executor Service for your need.\r\n\r\n```\r\nDeferredManager dm = new DefaultDeferredManager(myExecutorService);\r\n```\r\n\r\n<a name=\"example-runnable-callable\"></a>Runnable and Callable\r\n---------------------\r\nYou can use Callable and Runnable almost like a Promise without any additional work.\r\n\r\n```java\r\nDeferredManager dm = new DefaultDeferredManager();\r\ndm.when(new Callable<Integer>(){\r\n  public Integer call() {\r\n    // return something\r\n    // or throw a new exception\r\n  }\r\n}).done(new DoneCallback<Integer>() {\r\n  public void onDone(Integer result) {\r\n    ...\r\n  }\r\n}).fail(new FailCallback<Throwable>() {\r\n  public void onFail(Throwable e) {\r\n    ...\r\n  }\r\n});\r\n```\r\n\r\nIf you need to notify progress within your Callable or Runnable, you either need to create your own Deferred object and Promise, or you can use DeferredCallable and DeferredRunnable.\r\n\r\nUse your own Deferred object\r\n\r\n```java\r\nfinal Deferred deferred = ...\r\nPromise promise = deferred.promise();\r\npromise.then(…);\r\nRunnable r = new Runnable() {\r\n  public void run() {\r\n    while (…) {\r\n      deferred.notify(myProgress);\r\n    }\r\n    deferred.resolve(\"done\");\r\n  }\r\n}\r\n```\r\n\r\nOr, extending DeferredRunnable\r\n\r\n```java\r\nDeferredManager dm = …;\r\ndm.when(new DeferredRunnable<Double>(){\r\n  public void run() {\r\n    while (…) {\r\n      notify(myProgress);\r\n    }\r\n  }\r\n}).then(…);\r\n```\r\n\r\n<a name=\"example-wait\"></a>Wait and WaitSafely\r\n-------------------\r\n> Since 1.0.1\r\n\r\nNormally, when using this framework, you would want to do things asynchronously.  However, if there is a need to wait for all deferred tasks to finish, you can use Object.wait or Promise.waitSafely methods.\r\n\r\n```java\r\nPromise p = dm.when(...)\r\n  .done(...)\r\n  .fail(...)\r\n\r\nsynchronized (p)\r\n  while (p.isPending()) {\r\n    try {\r\n      p.wait();\r\n    } catch (InterruptedException e) { ... }\r\n  }\r\n}\r\n```\r\n\r\nAlternatively, you can use a more simplified shortcut\r\n```java\r\nPromise p = dm.when(...)\r\n  .done(...)\r\n  .fail(...)\r\n\r\ntry {\r\n  p.waitSafely();\r\n} catch (InterruptedException e) {\r\n  ... \r\n}\r\n```\r\n\r\n<a name=\"example-android\"></a>Android Support\r\n---------------\r\n> Since 1.1.0-Beta1\r\n\r\n```jdeferred-android``` is now available, and it can be included just like any other Android libraries!\r\nIt also uses Android Maven pugin and builts apklib file.  If you use Android Maven plugin, you can include\r\ndependency:\r\n\r\nAPKLIB:\r\n```xml\r\n<dependency>\r\n  <groupId>org.jdeferred</groupId>\r\n  <artifactId>jdeferred-android</artifactId>\r\n  <version>...</version>\r\n  <type>apklib</type>\r\n</dependency>\r\n```\r\n\r\nAAR:\r\n> Since 1.2.0-Beta1\r\n\r\n```xml\r\n<dependency>\r\n  <groupId>org.jdeferred</groupId>\r\n  <artifactId>jdeferred-android-aar</artifactId>\r\n  <version>...</version>\r\n  <type>aar</type>\r\n</dependency>\r\n```\r\n\r\n```jdeferred-android``` introduces a new ```DeferredManager``` implementation called ```AndroidDeferredManager```.\r\n```AndroidDeferredManager``` makes sure that callbacks are executed in UI Thread rather than background Thread\r\nin order for callbacks to make UI updates.  Alternatively, callbacks can also implement ```AndroidExecutionScopeable```\r\ninterface to fine-grain control whether the callback should execute in UI Thread or background Thread.\r\n\r\n```AndroidDeferredManager``` also supports new ```DeferredAsyncTask``` object.  This object is based on \r\nAndroid's ```AsyncTask```.\r\n\r\nIf you need to always execute callbacks in background thread, then you can continue to use ```DefaultDeferredManager```.\r\n\r\nLastly, because JDeferred use SLF4J - you can further route log messages using ```slf4j-android```.\r\n\r\n\r\n<a name=\"example-async-servlet\"></a>Asynchronous Servlet\r\n--------------------\r\nHere is a sample code on how to use JDeferred with Asynchronous Servlet!\r\n\r\n```java\r\n@WebServlet(value = \"/AsyncServlet\", asyncSupported = true)\r\npublic class AsyncServlet extends HttpServlet {\r\n  private static final long serialVersionUID = 1L;\r\n  private ExecutorService executorService = Executors.newCachedThreadPool();\r\n  private DeferredManager dm = new DefaultDeferredManager(executorService);\r\n\r\n  protected void doGet(HttpServletRequest request,\r\n                       HttpServletResponse response) throws ServletException, IOException {\r\n    final AsyncContext actx = request.startAsync(request, response);\r\n    \r\n    dm.when(new Callable<String>() {\r\n      @Override\r\n      public String call() throws Exception {\r\n        if (actx.getRequest().getParameter(\"fail\") != null) {\r\n          throw new Exception(\"oops!\");\r\n        }\r\n        Thread.sleep(2000);\r\n        return \"Hello World!\";\r\n      }\r\n    }).then(new DoneCallback<String>() {\r\n      @Override\r\n      public void onDone(String result) {\r\n        actx.getRequest().setAttribute(\"message\", result);\r\n        actx.dispatch(\"/hello.jsp\");\r\n      }\r\n    }).fail(new FailCallback<Throwable>() {\r\n      @Override\r\n      public void onFail(Throwable exception) {\r\n        actx.getRequest().setAttribute(\"exception\", exception);\r\n        actx.dispatch(\"/error.jsp\");\r\n      }\r\n    });\r\n  }\r\n}\r\n```\r\n<a name=\"example-lambda\"></a>Java 8 Lambda\r\n-------------\r\nNow this is pretty cool when used with Java 8 Lambda!\r\n\r\n```Java\r\ndm.when(() -> {\r\n  return \"Hey!\";\r\n}).done(r -> System.out.println(r));\r\n\r\ndm.when(\r\n  () -> { return \"Hello\"; },\r\n  () -> { return \"World\"; }\r\n).done(rs ->\r\n  rs.forEach(r -> System.out.println(r.getResult()))\r\n);\r\n```\r\n\r\n<a name=\"example-groovy\"></a>Groovy\r\n-----\r\nYou can also easily use with Groovy!\r\n\r\n```Groovy\r\n@Grab('org.jdeferred:jdeferred-core:1.2.4')\r\nimport org.jdeferred.*\r\nimport org.jdeferred.impl.*\r\n\r\ndef deferred = new DeferredObject()\r\ndef promise = deferred.promise()\r\n\r\npromise.done { result ->\r\n  println \"done: $result\" \r\n}.fail { rejection ->\r\n  println \"fail: $rejection\"\r\n}.always { state, result, rejection ->\r\n  println \"always\"\r\n}\r\n\r\ndeferred.resolve(\"done\")\r\n```\r\n\r\n<!-- Google Code for GitHub Visit Conversion Page -->\r\n<script type=\"text/javascript\">\r\n/* <![CDATA[ */\r\nvar google_conversion_id = 974052972;\r\nvar google_conversion_language = \"en\";\r\nvar google_conversion_format = \"3\";\r\nvar google_conversion_color = \"ffffff\";\r\nvar google_conversion_label = \"wsVZCOycvgkQ7Ly70AM\";\r\nvar google_conversion_value = 0;\r\nvar google_remarketing_only = false;\r\n/* ]]> */\r\n</script>\r\n<script type=\"text/javascript\" src=\"//www.googleadservices.com/pagead/conversion.js\">\r\n</script>\r\n<noscript>\r\n<div style=\"display:inline;\">\r\n<img height=\"1\" width=\"1\" style=\"border-style:none;\" alt=\"\" src=\"//www.googleadservices.com/pagead/conversion/974052972/?value=0&amp;label=wsVZCOycvgkQ7Ly70AM&amp;guid=ON&amp;script=0\"/>\r\n</div>\r\n</noscript>\r\n",
  "google": "UA-7701209-6",
  "note": "Don't delete this file! It's used internally to help with page regeneration."
}