com.github.dm.jrt.android.v4.core

Class JRoutine

java.lang.Object

com.github.dm.jrt.core.JRoutine

com.github.dm.jrt.android.core.JRoutine

com.github.dm.jrt.android.v4.core.JRoutine

public class JRoutine
extends JRoutine

This utility class extends the base one in order to support additional routine builders specific to the Android platform.
Routine invocations created through the returned builders can be safely restored after a change in the configuration, so to avoid duplicated calls and memory leaks. Be aware, though, that the invocation results will be dispatched on the configured looper thread, no matter the calling one was, so that, waiting for the outputs right after the routine invocation, may result in a deadlock.
Note that the configuration of the maximum number of concurrent invocations might not work as expected. In fact, the number of running loaders cannot be computed.
Note also that the input data will be cached, and the results will be produced only after the invocation channel is closed, so be sure to avoid streaming inputs in order to prevent starvation or out of memory errors.

The equals() and hashCode() methods of the input parameter objects and the invocation factory, might be employed to check for clashing of invocation instances or compute the loader ID.
In case the caller could not guarantee the correct behavior of the aforementioned method implementations, a user defined ID or an input independent clash resolution should be used in order to avoid unexpected results.

The routine invocations will be identified by an ID number. In case a clash is detected, that is, an already running loader with the same ID exists at the time the new invocation is executed, the clash is resolved based on the strategy specified through the builder. When a clash cannot be resolved, for example when invocations with different implementations share the same ID, the new invocation is aborted with a InvocationTypeException.

For example, in order to get a resource from the network, needed to fill an activity UI:

     

         @Override
         protected void onCreate(final Bundle savedInstanceState) {

             super.onCreate(savedInstanceState);
             setContentView(R.layout.my_activity_layout);

             if (savedInstanceState != null) {

                 mResource = savedInstanceState.getParcelable(RESOURCE_KEY);
             }

             if (mResource != null) {

                 displayResource(mResource);

             } else {

                 final Routine<URI, MyResource> routine =
                         JRoutine.on(contextFrom(this), factoryOf(LoadResource.class))
                                 .buildRoutine();
                 routine.asyncCall(RESOURCE_URI)
                        .passTo(new TemplateOutputConsumer<MyResource>() {

                            @Override
                            public void onError(@Nullable final Throwable error) {

                                displayError(error);
                            }

                            @Override
                            public void onOutput(final MyResource resource) {

                                mResource = resource;
                                displayResource(resource);
                            }
                        });
             }
         }

         @Override
         protected void onSaveInstanceState(final Bundle outState) {

             super.onSaveInstanceState(outState);
             outState.putParcelable(RESOURCE_KEY, mResource);
         }
     
 

The above code will ensure that the loading process survives any configuration change and the resulting resource is dispatched only once.

Note that the invocation may be implemented so to run in a separate service:

     

         public class LoadResource extends TemplateContextInvocation<URI, MyResource> {

             private Routine<URI, MyResource> mRoutine;

             @Override
             public void onContext(@Nonnull final Context context) {

                 super.onContext(context);
                 mRoutine =
                      JRoutine.on(serviceFrom(context), targetInvocation(LoadResourceUri.class))
                                    .buildRoutine();
             }

             @Override
             public void onInput(final URI uri,
                     @Nonnull final ResultChannel<MyResource> result) {

                 result.pass(mRoutine.asyncCall(uri));
             }
         }
     
 

Created by davide-maestroni on 12/08/2014.

Constructor Summary

Constructors

Constructor and Description
JRoutine()

Method Summary

Methods

Modifier and Type	Method and Description
static LoaderChannelBuilder	on(LoaderContext context) Returns a builder of an output channel bound to the loader identified by the ID specified in the loader configuration. If no invocation with the specified ID is running at the time of the channel creation, the output will be aborted with a MissingInvocationException. Note that the built routine results will be always dispatched on the configured looper thread, thus waiting for the outputs immediately after its invocation may result in a deadlock.
static <IN,OUT> LoaderRoutineBuilder<IN,OUT>	on(LoaderContext context, ContextInvocationFactory<IN,OUT> factory) Returns a builder of routines bound to the specified context. In order to prevent undesired leaks, the class of the specified factory must be static, and should never be a platform component (like Activity, Fragment, etc.). Note that the built routine results will be always dispatched on the configured looper thread, thus waiting for the outputs immediately after its invocation may result in a deadlock.
static LoaderObjectRoutineBuilder	on(LoaderContext context, ContextInvocationTarget target) Returns a builder of routines bound to the specified context, wrapping the specified target object. In order to customize the object creation, the caller must employ an implementation of a FactoryContext as the application context. Note that the built routine results will be always dispatched on the configured looper thread, thus waiting for the outputs immediately after its invocation may result in a deadlock.

Methods inherited from class com.github.dm.jrt.android.core.JRoutine

on, on

Methods inherited from class com.github.dm.jrt.core.JRoutine

on, on, transport

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JRoutine

public JRoutine()

Method Detail

on

@Nonnull
public static LoaderChannelBuilder on(@Nonnull
                              LoaderContext context)

Returns a builder of an output channel bound to the loader identified by the ID specified in the loader configuration.
If no invocation with the specified ID is running at the time of the channel creation, the output will be aborted with a MissingInvocationException.
Note that the built routine results will be always dispatched on the configured looper thread, thus waiting for the outputs immediately after its invocation may result in a deadlock.

Parameters:

context - the routine context.

Returns:

the channel builder instance.

on

@Nonnull
public static <IN,OUT> LoaderRoutineBuilder<IN,OUT> on(@Nonnull
                                               LoaderContext context,
                                               @Nonnull
                                               ContextInvocationFactory<IN,OUT> factory)

Returns a builder of routines bound to the specified context.
In order to prevent undesired leaks, the class of the specified factory must be static, and should never be a platform component (like Activity, Fragment, etc.).
Note that the built routine results will be always dispatched on the configured looper thread, thus waiting for the outputs immediately after its invocation may result in a deadlock.

Type Parameters:

IN - the input data type.

OUT - the output data type.

Parameters:

context - the routine context.

factory - the invocation factory.

Returns:

the routine builder instance.

Throws:

IllegalArgumentException - if the class of the specified factory is not static.

on

@Nonnull
public static LoaderObjectRoutineBuilder on(@Nonnull
                                    LoaderContext context,
                                    @Nonnull
                                    ContextInvocationTarget target)

Returns a builder of routines bound to the specified context, wrapping the specified target object.
In order to customize the object creation, the caller must employ an implementation of a FactoryContext as the application context.
Note that the built routine results will be always dispatched on the configured looper thread, thus waiting for the outputs immediately after its invocation may result in a deadlock.

Parameters:

context - the routine context.

target - the invocation target.

Returns:

the routine builder instance.