Iris

Convenient wrapper library to perform network queries using Retrofit and Android Priority Job Queue (Job Manager)

STILL IN DEVELOPMENT

Dependency
How to use the Iris compiler
How to use Iris standalone (i.e., without its compiler)
Benefits
Logo credits

Dependency

In the top-level build.gradle file:

buildscript {
    dependencies {
        classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8'
    }
}

In the project build.gradle file:

apply plugin: 'com.neenbedankt.android-apt'

repositories {
    maven {
        url 'https://dl.bintray.com/guddy/maven/'
    }
}

dependencies {
    compile 'fr.guddy.iris:iris:0.0.7'
    apt 'fr.guddy.iris:compiler:0.0.7'
}

How to use the Iris compiler

Create a retrofit interface as usual

public interface ApiService {
    @GET("users/{user}/repos")
    Call<List<RepoDTO>> listRepos(@NonNull @Path("user") final String user);
}

Supported annotations are @DELETE, @GET, @HEADER, @HTTP, @PATCH, @POST, @PUT.

The annotation processor will generate the following query class:

public abstract class AbstractQueryListRepos extends AbstractQuery<List<RepoDTO>> {
  public final String user;

  private transient List<RepoDTO> mResult;

  protected AbstractQueryListRepos(final Params params, final String user) {
    super(params);
    this.user = user;
  }

  public List<RepoDTO> getResult() {
    return mResult;
  }

  @Override
  protected void execute() throws Throwable {
    mResponse = getApiService().listRepos(user).execute();
    mResult = mResponse.body();
  }

  @Override
  protected void onQueryDidFinish() {
  }

  protected abstract ApiService getApiService();

  public static final class EventQueryListReposDidFinish extends AbstractEventQueryDidFinish<AbstractQueryListRepos> {
    public EventQueryListReposDidFinish(final AbstractQueryListRepos query) {
      super(query);
    }
  }
}

The annotation processor will generate the following query class:

public class ApiServiceQueryFactory extends AbstractQueryFactory {
  public ApiServiceQueryFactory(final JobManager pJobManager, final MerlinsBeard pMerlinsBeard) {
    super(pJobManager, pMerlinsBeard);
  }

  public boolean startAbstractQueryListRepos(final AbstractQueryListRepos pQuery) {
    return startQuery(pQuery);
  }
}

now just subclass AbstractQueryListRepos as follows to provide the ApiService instance and deal with query ending:

public class QueryListRepos extends AbstractQueryListRepos {

    public QueryListRepos(@NonNull final String pUser) {
        super(new Params(1), pUser);
    }

    @Override
    protected ApiService getApiService() {
        return IrisApplication.getInstance()
                .getApplicationComponent()
                .apiService();
    }

    @Override
    protected void onQueryDidFinish() {
        IrisApplication.getInstance()
                .getApplicationComponent()
                .eventBus()
                .post(new EventQueryListReposDidFinish(this));
    }
}

start the query using the factory and test if it's return true or false:

if(queryFactory.startAbstractQueryListRepos(new QueryListRepos("RoRoche"))) {
  // query started
} else {
  // no network and not a persistent query
}

How to use Iris standalone (i.e., without its compiler)

Subclass AbstractQuery

public class QueryGetRepos extends AbstractQuery<List<RepoDTO>> {

    public final String user;

    public QueryGetRepos(@NonNull final String pUser) {
        super(new Params(1));
        user = pUser;
    }

    @Override
    protected void execute() throws Throwable {
        // TODO perform network query thanks to retrofit
    }

    @Override
    protected void onQueryDidFinish() {
        // TODO deal with results
    }
}

Subclass AbstractEventQueryDidFinish

public static final class EventQueryGetReposDidFinish extends AbstractEventQueryDidFinish<QueryGetRepos> {
    public EventQueryGetReposDidFinish(final QueryGetRepos pQuery) {
        super(pQuery);
    }
}

Subclass AbstractQueryFactory :

public class QueryFactory extends AbstractQueryFactory {
    public QueryFactory(final JobManager pJobManager, final MerlinsBeard pMerlinsBeard) {
        super(pJobManager, pMerlinsBeard);
    }

    public boolean startQueryListRepos(@NonNull final String pUser) {
        return startQuery(new QueryListRepos(pUser));
    }
}

Benefits

processing the retrofit interface, the compiler generates all of the boilerplate code
developer can focus on the specific job to do when the HTTP request is finished (for example: save data to local storage, by overriding the execute method)
the "Iris" library can be used without its compiler
it improves the network layer with a normalized structure
it's DI ready (cf. sample app using Dagger2)
it's Event-buses ready (cf. sample app using greenrobot's EventBus)

Logo credits

Nature graphic by Freepik from Flaticon is licensed under CC BY 3.0. Made with Logo Maker

RoRoche/Iris