EasyMVP

A powerful, and very simple MVP library with annotation processing and bytecode weaving.

EasyMVP eliminates the boilerplate code for dealing with MVP implementation.

📖 Chinese Readme 中文文档

• Features
• Installation
• Usage
  • Presenter
  • View Annotations
  • Injecting with Dagger
• Clean Architecture Usage
  • UseCase
  • DataMapper
• FAQ
• Documentations
• Demo
• Author
• License
• Changelog

Features

• Easy integration
• Less boilerplate
• Composition over inheritance
• Implement MVP with just few annotations
• Use Loaders to preserve presenters across configurations changes
• Support Clean Architecture approach.

Installation

Configure your project-level build.gradle to include the 'easymvp' plugin:

buildscript {
  repositories {
    ...
    maven { url  "http://dl.bintray.com/6thsolution/easymvp" }
   }
  dependencies {
    classpath 'com.sixthsolution.easymvp:easymvp-plugin:1.2.0-beta10'
  }
}
allprojects {
  repositories {
      ...
      maven { url  "http://dl.bintray.com/6thsolution/easymvp" }
  }
}

Then, apply the 'easymvp' plugin in your module-level build.gradle:

apply plugin: 'easymvp'

android {
  ...
}

There is no need for android-apt plugin for android gradle plugin version 2.2.0-alpha1 or higher. But if your are using it, please apply easymvp plugin after android-apt plugin.

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

For reactive API, simply apply the 'easymvp-rx' plugin in your module-level build.gradle and then add the RxJava dependency:

apply plugin: 'easymvp-rx'

dependencies {
  compile 'io.reactivex:rxjava:x.y.z'
}

Also EasyMVP supports RxJava2:

apply plugin: 'easymvp-rx2'

dependencies {
  compile 'io.reactivex.rxjava2:rxjava:x.y.z'
}

Note: All snapshot versions are available on jfrog

Usage

First thing you will need to do is to create your view interface.

public interface MyView {
    void showResult(String resultText);

    void showError(String errorText);
}

Then you should implement MyView in your Activity, Fragment or CustomView. But why?

• Improve unit testability. You can test your presenter without any android SDK dependencies.
• Decouple the code from the implementation view.
• Easy stubbing. For example, you can replace your Activity with a Fragment without any changes in your presenter.
• High level details (such as the presenter), can't depend on low level concrete details like the implementation view.

Presenter

Presenter acts as the middle man. It retrieves data from the data-layer and shows it in the View.

You can create a presenter class by extending of the AbstractPresenter or RxPresenter (available in reactive API).

public class MyPresenter extends AbstractPresenter<MyView> {

}

To understand when the lifecycle methods of the presenter are called take a look at the following table:

Presenter	Activity	Fragment	View
onViewAttached	onStart	onResume	onAttachedToWindow
onViewDetached	onStop	onPause	onDetachedFromWindow
onDestroyed	onDestroy	onDestroy	onDetachedFromWindow

View Annotations

Well, here is the magic part. There is no need for any extra inheritance in your Activity, Fragment or View classes to bind the presenter lifecycle.

Presenter's creation, lifecycle-binding, caching and destruction gets handled automatically by these annotations.

• @ActivityView for all activities based on AppCompatActivity.
• @FragmentView for all fragments based on Default Fragment or Support Fragment
• @CustomView for all views based on View.

For injecting presenter into your activity/fragment/view, you can use @Presenter annotation. Also during configuration changes, previous instance of the presenter will be injected.

EasyMVP uses Loaders to preserve presenters across configurations changes.

Presenter instance will be set to null, after onDestroyed method injection.

@ActivityView example:

@ActivityView(layout = R.layout.my_activity, presenter = MyPresenter.class)
public class MyActivity extends AppCompatActivity implements MyView {

    @Presenter
    MyPresenter presenter;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    }

    @Override
    protected void onStart() {
        super.onStart();
        // Now presenter is injected.
    }
    
    @Override
    public void showResult(String resultText) {
        //do stuff
    }
    
    @Override
    public void showError(String errorText) {
        //do stuff
    }
}

• You can specify the layout in @ActivityView#layout and EasyMVP will automatically inflate it for you.

@FragmentView example:

@FragmentView(presenter = MyPresenter.class)
public class MyFragment extends Fragment implements MyView {

    @Presenter
    MyPresenter presenter;
    
    @Override
    public void onResume() {
        super.onResume();
        // Now presenter is injected.
    }
    
    @Override
    public void showResult(String resultText) {
        //do stuff
    }
    
    @Override
    public void showError(String errorText) {
        //do stuff
    }
}

@CustomView example:

@CustomView(presenter = MyPresenter.class)
public class MyCustomView extends View implements MyView {

    @Presenter
    MyPresenter presenter;
    
    @Override
    protected void onAttachedToWindow() {
        super.onAttachedToWindow();
        // Now presenter is injected.
    }
    
    @Override
    public void showResult(String resultText) {
        //do stuff
    }
    
    @Override
    public void showError(String errorText) {
        //do stuff
    }
}

Injecting with Dagger

@Presenter annotation will instantiate your presenter class by calling its default constructor, So you can't pass any objects to the constructor.

But if you are using Dagger, you can use its constructor injection feature to inject your presenter.

So what you need is make your presenter injectable and add @Inject annotation before @Presenter. Here is an example:

public class MyPresenter extends AbstractPresenter<MyView> {

    @Inject
    public MyPresenter(UseCase1 useCase1, UseCase2 useCase2){
    
    }
}

@ActivityView(layout = R.layout.my_activity, presenter = MyPresenter.class)
public class MyActivity extends AppCompatActivity implements MyView {

    @Inject
    @Presenter
    MyPresenter presenter;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        SomeDaggerComponent.injectTo(this);
        super.onCreate(savedInstanceState);
     }
        
    //...
}

Don't inject dependencies after super.onCreate(savedInstanceState); in activities, super.onActivityCreated(bundle); in fragments and super.onAttachedToWindow(); in custom views.

Clean Architecture Usage

You can follow the principles of Clean Architecture by applying 'easymvp-rx' plugin. Previous part was all about the presentation-layer, Now lets talk about the domain-layer.

Domain Layer holds all your business logic, it encapsulates and implements all of the use cases of the system. This layer is a pure java module without any android SDK dependencies.

UseCase

UseCases are the entry points to the domain layer. These use cases represent all the possible actions a developer can perform from the presentation layer.

Each use case should run off the main thread(UI thread), to avoid reinventing the wheel, EasyMVP uses RxJava to achieve this.

You can create a use case class by extending of the following classes:

• ObservableUseCase
• CompletableUseCase

public class SuggestPlaces extends ObservableUseCase<List<Place>, String> {

    private final SearchRepository searchRepository;

    public SuggestPlaces(SearchRepository searchRepository, 
                         UseCaseExecutor useCaseExecutor,
                         PostExecutionThread postExecutionThread) {
        super(useCaseExecutor, postExecutionThread);
        this.searchRepository = searchRepository;
    }

    @Override
    protected Observable<List<Place>> interact(@NonNull String query) {
        return searchRepository.suggestPlacesByName(query);
    }
}

public class InstallTheme extends CompletableUseCase<File> {

    private final ThemeManager themeManager;
    private final FileManager fileManager;
    
    public InstallTheme(ThemeManager themeManager,
                           FileManager fileManager,
                           UseCaseExecutor useCaseExecutor,
                           PostExecutionThread postExecutionThread) {
        super(useCaseExecutor, postExecutionThread);
        this.themeManager = themeManager;
        this.fileManager = fileManager;
    }

    @Override
    protected Completable interact(@NonNull File themePath) {
        return themeManager.install(themePath)
                .andThen(fileManager.remove(themePath))
                .toCompletable();
    }

}

And the implementations of UseCaseExecutor and PostExecutionThread are:

public class UIThread implements PostExecutionThread {
    
    @Override
    public Scheduler getScheduler() {
        return AndroidSchedulers.mainThread();
    }
}

public class BackgroundThread implements UseCaseExecutor {

    @Override
    public Scheduler getScheduler() {
        return Schedulers.io();
    }
}

DataMapper

Each DataMapper transforms entities from the format most convenient for the use cases, to the format most convenient for the presentation layer.

But, why is it useful?

Let's see SuggestPlaces use case again. Assume that you passed the Mon query to this use case and it emitted:

• Montreal
• Monterrey
• Montpellier

But you want to bold the Mon part of each suggestion like:

• Montreal
• Monterrey
• Montpellier

So, you can use a data mapper to transform the Place object to the format most convenient for your presentation layer.

public class PlaceSuggestionMapper extends DataMapper<List<SuggestedPlace>, List<Place>> {
    
    @Override
    public List<SuggestedPlace> call(List<Place> places) {
        //TODO for each Place object, use SpannableStringBuilder to make a partial bold effect
    }
}

Note that Place entity lives in the domain layer but SuggestedPlace entity lives in the presentation layer.

So, How to bind DataMapper to ObservableUseCase?

public class MyPresenter extends RxPresenter<MyView> {

    private SuggestPlace suggestPlace;
    private SuggestPlaceMapper suggestPlaceMapper;
    
    @Inject
    public MyPresenter(SuggestPlace suggestPlace, SuggestPlaceMapper suggestPlaceMapper){
        this.suggestPlace = suggestPlace;
        this.suggestPlaceMapper = suggestPlaceMapper;
    }
    
    void suggestPlaces(String query){
        addSubscription(
                       suggestPlace.execute(query)
                                     .map(suggetsPlaceMapper)
                                     .subscribe(suggestedPlaces->{
                                           //do-stuff
                                      })
                        );
    }
}

FAQ

How does EasyMVP work under the hood?

• For each annotated class with @ActivityView, @FragmentView or @CustomView, EasyMVP generates *_ViewDelegate class in the same package. These classes are responsible for binding presenter's lifecycle.
• EasyMVP uses bytecode weaving to call delegate classes inside your view implementation classes. You can find these manipulated classes in build/weaver folder.

Is there any restrictions on using EasyMVP?

• EasyMVP uses android's transform API for bytecode weaving. Related to this issue the Jack toolchain doesn't support it yet. (Jack toolchain is now deprecated)

Does it support kotlin?

• Yes, See this issue for details.

Documentations

EasyMVP API: Javadocs for the current API release

EasyMVP RX-API: Javadocs for the current RX-API (Clean Architecture API) release

EasyMVP RX2-API: Javadocs for the current RX2-API (Clean Architecture API) release

Demo

CleanTvMaze Shows how to use EasyMVP with Kotlin

TVProgram_Android Shows how to use EasyMVP with Java

Author

Saeid Masoumihajiagha

License

Copyright 2016-2017 6thSolution Technologies Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.