jdeferred

JDifféré 2.x

JDeferred est une bibliothèque Java Deferred/Promise similaire à l'objet différé de JQuery.

Inspiré par JQuery et Android Deferred Object.

Si vous utilisez JDeferred 1.x, consultez la documentation de JDeferred 1.x.

Caractéristiques

• Objet différé et promesse
• Rappels de promesses
  • .then(…)
  • .filter(…)
  • .pipe(…)
  • .done(…)
  • .fail(…)
  • .progress(…)
  • .always(…)
  • .pipeAlways(…)
• De multiples promesses
  • .when(p1, p2, p3, …).then(…)
  • .race(p1, p2, p3, …).then(…)
  • .settle(p1, p2, p3, …).then(…)
• Wrappers appelables et exécutables
  • .when(new Runnable() {…})
  • .race(new Runnable() {…})
  • .settle(new Runnable() {…})
• Utilise le service d'exécution
• Prise en charge des génériques Java
  • Deferred<Integer, Exception, Double> deferred;
  • deferred.resolve(10);
  • deferred.reject(new Exception());
  • deferred.notify(0.80);
• Prise en charge d'Android
• Compatible Java 8 Lambda
• Oui, c'est sur le référentiel central Maven !

Maven

< dependency >
    < groupId >org.jdeferred.v2</ groupId >
    < artifactId >jdeferred-core</ artifactId >
    < version >${version}</ version >
</ dependency >

Graduation

 compile 'org.jdeferred.v2:jdeferred-core:${version}'

Recherchez les versions disponibles sur le référentiel central Maven.

Compatibilité

Rapports de compatibilité entre versions :

• 1.2.6 à 2.0.0

Exemples rapides

Objet différé et promesse

 Deferred deferred = new DeferredObject ();
Promise promise = deferred . promise ();
promise . done ( new DoneCallback () {
  public void onDone ( Object result ) {
    ...
  }
}). fail ( new FailCallback () {
  public void onFail ( Object rejection ) {
    ...
  }
}). progress ( new ProgressCallback () {
  public void onProgress ( Object progress ) {
    ...
  }
}). always ( new AlwaysCallback () {
  public void onAlways ( State state , Object result , Object rejection ) {
    ...
  }
});

Avec la référence à l'objet différé, vous pouvez alors déclencher des actions/mises à jour :

 deferred . resolve ( "done" );
deferred . reject ( "oops" );
deferred . notify ( "100%" );

Filtre

Utilisez .filter(...) au lieu de .then(...) depuis la version 2.0.0-Beta2

 Deferred d = …;
Promise p = d . promise ();
Promise filtered = p . filter ( new DoneFilter < Integer , Integer >() {
  public Integer filterDone ( Integer result )
    return result * 10 ;
  }
});

filtered . done ( new DoneCallback < Integer >() {
  public void onDone ( Integer result ) {
    // result would be original * 10
    System . out . println ( result );
  }
});

d . resolve ( 3 ) -> 30. 

Tuyau

Utilisez .pipe(...) au lieu de .then(...) depuis la version 2.0.0-Beta2

 Deferred d = ...;
Promise p = d . promise ();

p . pipe ( new DonePipe < Integer , Integer , Exception , Void >() {
  public Deferred < Integer , Exception , Void > pipeDone ( Integer result ) {
    if ( result < 100 ) {
      return new DeferredObject < Integer , Void , Void >(). resolve ( result );
    } else {
      return new DeferredObject < Integer , Void , Void >(). reject ( new Exception (...));
    }
  }
}). done (...). fail (...);

d . resolve ( 80 ) -> done !
d . resolve ( 100 ) -> fail !

Gestionnaire différé

 DeferredManager dm = new DefaultDeferredManager ();
Promise p1 , p2 , p3 ;
// initialize p1, p2, p3
dm . when ( p1 , p2 , p3 )
  . done (…)
  . fail (…)

Vous pouvez également spécifier un service d'exécution selon vos besoins.

 DeferredManager dm = new DefaultDeferredManager(myExecutorService);

Exécutable et appelable

Vous pouvez utiliser Callable et Runnable presque comme une promesse sans aucun travail supplémentaire.

 DeferredManager dm = new DefaultDeferredManager ();
dm . when ( new Callable < Integer >(){
  public Integer call () {
    // return something
    // or throw a new exception
  }
}). done ( new DoneCallback < Integer >() {
  public void onDone ( Integer result ) {
    ...
  }
}). fail ( new FailCallback < Throwable >() {
  public void onFail ( Throwable e ) {
    ...
  }
});

Si vous devez notifier la progression de votre Callable ou Runnable, vous devez soit créer votre propre objet Deferred et Promise, soit utiliser DeferredCallable et DeferredRunnable.

Utilisez votre propre objet différé

 final Deferred deferred = ...
Promise promise = deferred . promise ();
promise . then (…);
Runnable r = new Runnable () {
  public void run () {
    while (…) {
      deferred . notify ( myProgress );
    }
    deferred . resolve ( "done" );
  }
}

Ou, en étendant DeferredRunnable

 DeferredManager dm = …;
dm . when ( new DeferredRunnable < Double >(){
  public void run () {
    while (…) {
      notify ( myProgress );
    }
  }
}). then (…);

Attendez et attendez en toute sécurité

Depuis 1.0.1

Normalement, lorsque vous utilisez ce framework, vous souhaiterez faire les choses de manière asynchrone. Cependant, s'il est nécessaire d'attendre la fin de toutes les tâches différées, vous pouvez utiliser les méthodes Object.wait ou Promise.waitSafely.

 Promise p = dm . when (...)
  . done (...)
  . fail (...)

synchronized ( p )
  while ( p . isPending ()) {
    try {
      p . wait ();
    } catch ( InterruptedException e ) { ... }
  }
}

Vous pouvez également utiliser un raccourci plus simplifié

 Promise p = dm . when (...)
  . done (...)
  . fail (...)

try {
  p . waitSafely ();
} catch ( InterruptedException e ) {
  ... 
}

Java 8 Lambda

Maintenant, c'est plutôt cool lorsqu'il est utilisé avec Java 8 Lambda !

 dm . when (() -> {
  return "Hey!" ;
}). done ( r -> System . out . println ( r ));

dm . when (
  () -> { return "Hello" ; },
  () -> { return "World" ; }
). done ( rs ->
  rs . forEach ( r -> System . out . println ( r . getResult ()))
);

Quand

Les appels à when avec plusieurs arguments aboutissent à une Promise selon laquelle les signaux fail au premier rejet ou les signaux done avec toutes les valeurs calculées.

Scénario de réussite

 Callable < Integer > c1 = () -> 1 ;
Callable < Integer > c2 = () -> 2 ;
Callable < Integer > c3 = () -> 3 ;
Promise < MultipleResults3 < Integer , Integer , Integer >, OneReject < Throwable >, MasterProgress > p = dm . when ( c1 , c2 , c3 );
p . done ( MultipleResults3 < Integer , Integer , Integer > r -> {
  Assert . assertEquals ( r . getFirst (), 1 );
  Assert . assertEquals ( r . getSecond (), 2 );
  Assert . assertEquals ( r . getThird (), 3 );
});

Scénario d'échec

 Callable < Integer > c1 = () -> 1 ;
Callable < Integer > c2 = () -> 2 ;
Callable < Integer > c3 = () -> throw new RuntimeException ( "boom!" );
Promise < MultipleResults3 < Integer , Integer , Integer >, OneReject < Throwable >, MasterProgress > p = dm . when ( c1 , c2 , c3 );
p . done ( MultipleResults3 < Integer , Integer , Integer > r -> Assert . fail ( "should not be called" ))
 . fail ( OneReject < Throwable > r -> Assert . assertEquals ( r . getReject (). getMessage (), "boom!" ));

Depuis 2.0.0

Les appels à when avec plusieurs arguments (jusqu'à cinq) produiront des résultats avec des getters typesafe.

Course

Depuis 2.0.0

Les appels à race avec plusieurs arguments aboutissent à une Promise selon laquelle les signaux fail au premier rejet ou les signaux done à la première résolution.

Scénario de réussite

 Callable < Integer > c1 = () -> { Thread . sleep ( 200 ); return 1 ; };
Callable < Integer > c2 = () -> { Thread . sleep ( 100 ); return 2 ; };
Callable < Integer > c3 = () -> { Thread . sleep ( 200 ); return 3 ; };
Promise < OneResult <?>, OneReject < Throwable >, Void > p = dm . race ( c1 , c2 , c3 );
p . done ( OneResult <?> r -> Assert . assertEquals ( r . getResult (), 2 ));

Scénario d'échec

 Callable < Integer > c1 = () -> { Thread . sleep ( 200 ); return 1 ; };
Callable < Integer > c2 = () -> { Thread . sleep ( 100 ); throw new RuntimeException ( "boom!" ); };
Callable < Integer > c3 = () -> { Thread . sleep ( 200 ); return 3 ; };
Promise < OneResult <?>, OneReject < Throwable >, Void > p = dm . race ( c1 , c2 , c3 );
p . done ( OneResult <?> r -> Assert . fail ( "should not be called" )
  . fail ( OneReject < Throwable > r -> Assert . assertEquals ( r . getReject (). getMessage (), "boom!" ));

Régler

Depuis 2.0.0

Les appels à settle avec plusieurs arguments aboutissent à une Promise qui rassemble toutes les résolutions et tous les rejets.

 Callable < Integer > c1 = () -> { Thread . sleep ( 200 ); return 1 ; };
Callable < Integer > c2 = () -> { Thread . sleep ( 100 ); throw new RuntimeException ( "boom!" ); };
Callable < Integer > c3 = () -> { Thread . sleep ( 200 ); return 3 ; };
Promise < AllValues , Throwable , MasterProgress >, Void > p = dm . race ( c1 , c2 , c3 );
p . done ( AllValues r -> {
  Assert . assertEquals ( r . get ( 0 ). getValue (), 1 );
  Assert . assertTrue ( r . get ( 1 ). getValue () instanceof RuntimeException );
  Assert . assertEquals ( r . get ( 2 ). getValue (), 3 );
});

Gestionnaire d'annulation

Depuis 2.0.0

Parfois, une tâche peut être annulée pendant son exécution et nécessiterait le nettoyage de toutes les ressources qu'elle aurait pu allouer. Vous pouvez définir une tâche qui implémente l'interface org.jdeferred2.CancellationHandler ou transmettre un argument supplémentaire à DeferredFutureTask avec une telle implémentation, par exemple

 final DataSource datasource = ...;
class DatabaseTask extends Runnable , CancellationHandler {
  @ Override
  public void run () {
    // perform computation with datasource
  }

  @ Override
  public void onCancel () {
    try {
      datasource . close ();
    } catch ( Exception e ) {
      throw new IllegalStateException ( e );
    }
  }
}

DeferredFutureTask < X > task = new DeferredFutureTask ( new DatabaseTask ());
dm . when ( task ). done (...)

Vous pouvez également transmettre CancellationHandler comme argument supplémentaire, par exemple

 final DataSource datasource = ...;
class DatabaseTask extends Runnable {
  @ Override
  public void run () {
    // perform computation with datasource
  }
}

class DatabaseCancellationHandler implements CancellationHandler {
  @ Override
  public void onCancel () {
    try {
      datasource . close ();
    } catch ( Exception e ) {
      throw new IllegalStateException ( e );
    }
  }
}

DeferredFutureTask < X > task = new DeferredFutureTask ( new DatabaseTask (), new DatabaseCancellationHandler ());
dm . when ( task ). done (...)

Groovy

Vous pouvez également facilement l'utiliser avec Groovy !

 @Grab ( ' org.jdeferred.v2:jdeferred-core:2.0.0 ' )
import org.jdeferred2.*
import org.jdeferred2.impl.*

def deferred = new DeferredObject ()
def promise = deferred . promise()

promise . done { result ->
  println " done: $r esult " 
} . fail { rejection ->
  println " fail: $r ejection "
} . always { state , result , rejection ->
  println " always "
}

deferred . resolve( " done " )

Prise en charge d'Android

Depuis 1.1.0-Beta1

jdeferred-android est maintenant disponible et peut être inclus comme n'importe quelle autre bibliothèque Android ! Il utilise également le plugin Android Maven et crée le fichier apklib. Si vous utilisez le plugin Android Maven, vous pouvez inclure la dépendance :

APKLIB avec Maven :

< dependency >
  < groupId >org.jdeferred.v2</ groupId >
  < artifactId >jdeferred-android</ artifactId >
  < version >${version}</ version >
  < type >apklib</ type >
</ dependency >

AAR avec Maven :

Depuis la version 1.2.0-Beta1

< dependency >
  < groupId >org.jdeferred.v2</ groupId >
  < artifactId >jdeferred-android-aar</ artifactId >
  < version >${version}</ version >
  < type >aar</ type >
</ dependency >

AAR avec Gradle :

 compile 'org.jdeferred.v2:jdeferred-android-aar:${version}'
// or
compile 'org.jdeferred.v2:jdeferred-android-aar:${version}@aar'

Recherchez les versions disponibles sur le référentiel central Maven.

jdeferred-android introduit une nouvelle implémentation DeferredManager appelée AndroidDeferredManager . AndroidDeferredManager s'assure que les rappels sont exécutés dans le thread d'interface utilisateur plutôt que dans le thread d'arrière-plan afin que les rappels effectuent des mises à jour de l'interface utilisateur. Alternativement, les rappels peuvent également implémenter l’interface AndroidExecutionScopeable pour contrôler finement si le rappel doit s’exécuter dans le thread d’interface utilisateur ou dans le thread d’arrière-plan.

AndroidDeferredManager prend également en charge le nouvel objet DeferredAsyncTask . Cet objet est basé sur AsyncTask d'Android.

Si vous devez toujours exécuter des rappels dans le thread d'arrière-plan, vous pouvez continuer à utiliser DefaultDeferredManager .

Enfin, étant donné que JDeferred utilise SLF4J, vous pouvez acheminer davantage les messages du journal en utilisant slf4j-android .

Servlet asynchrone

Voici un exemple de code sur la façon d'utiliser JDeferred avec un servlet asynchrone !

 @ WebServlet ( value = "/AsyncServlet" , asyncSupported = true )
public class AsyncServlet extends HttpServlet {
  private static final long serialVersionUID = 1L ;
  private ExecutorService executorService = Executors . newCachedThreadPool ();
  private DeferredManager dm = new DefaultDeferredManager ( executorService );

  protected void doGet ( HttpServletRequest request ,
                       HttpServletResponse response ) throws ServletException , IOException {
    final AsyncContext actx = request . startAsync ( request , response );
    
    dm . when ( new Callable < String >() {
      @ Override
      public String call () throws Exception {
        if ( actx . getRequest (). getParameter ( "fail" ) != null ) {
          throw new Exception ( "oops!" );
        }
        Thread . sleep ( 2000 );
        return "Hello World!" ;
      }
    }). then ( new DoneCallback < String >() {
      @ Override
      public void onDone ( String result ) {
        actx . getRequest (). setAttribute ( "message" , result );
        actx . dispatch ( "/hello.jsp" );
      }
    }). fail ( new FailCallback < Throwable >() {
      @ Override
      public void onFail ( Throwable exception ) {
        actx . getRequest (). setAttribute ( "exception" , exception );
        actx . dispatch ( "/error.jsp" );
      }
    });
  }
}

<script type="text/javascript"> /* */ </script> <script type="text/javascript" src="//www.googleadservices.com/pagead/conversion.js"> </script>

Dépréciations

v1.2.5

• DeferredManager.StartPolicy.MANAUL est obsolète et sera supprimé dans la prochaine version mineure. Utilisez plutôt DeferredManager.StartPolicy.MANUAL .