diff --git a/README.md b/README.md index 4d9c75d..8b7baac 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,19 @@ Lightweight library for unit testable and expressive multi-threading in Android. **ThreadPoster is in public beta**. I'm actively looking for feedback on project's structure, naming and usability. Bug reports are also welcome, of course. -## Usage +## Install + +To use ThreadPoster in your project, add this line to your Gradle dependencies configuration: + +``` +implementation 'com.techyourchance.threadposter:threadposter:0.8.0' +``` +## Usage At the core of this library are two simple classes: `UiThreadPoster` and `BackgroundThreadPoster`. +Code style note: if you're concerned with "boilerplate", you can replace explicit `Runnables` in the examples below with lambdas. + ### Executing code on UI thread In the following example, `updateText(String)` can be safely called on any thread. The actual UI update will always take place on UI thread: @@ -29,7 +38,7 @@ public class TextUpdater { ``` ### Executing code on "background" thread -In the following example, `fetchAndCacheUserDetails(String)` can be safely called on any thread. The actual network request and data caching will always take place on "background" thread (as opposed to UI thread): +In the following example, `fetchAndCacheUserDetails(String)` can be safely called on any thread. The actual network request and data caching will always take place on background thread (non-UI thread): ``` public class UpdateUserDetailsUseCase { @@ -51,68 +60,68 @@ public class UpdateUserDetailsUseCase { ``` ### Executing code on "background" thread and notifying Observers on UI thread -In the following example, `fetchAndCacheUserDetailsAndNotify(String)` can be safely called on any thread. The actual network request and data caching will always take place on "background" thread, and the observers will always be notified on UI thread: +In the [following example](sample/src/main/java/com/techyourchance/threadposters/FetchDataUseCase.java), `fetchData()` can be safely called on any thread. The actual data fetch will always take place on background thread, and the observers will always be notified on UI thread: ``` -public class UpdateUserDetailsUseCase extends BaseObservable { +public class FetchDataUseCase { public interface Listener { - void onUserDetailsUpdated(UserDetails userDetails); - void onUserDetailsUpdateFailed(String userId); + void onDataFetched(String data); + void onDataFetchFailed(); } + private final FakeDataFetcher mFakeDataFetcher; private final BackgroundThreadPoster mBackgroundThreadPoster; private final UiThreadPoster mUiThreadPoster; - private final UserDetailsEndpoint mUserDetailsEndpoint; - private final UserDetailsCache mUserDetailsCache; - public void fetchAndCacheUserDetailsAndNotify(final String userId) { + public void fetchData() { + // offload work to background thread mBackgroundThreadPoster.post(new Runnable() { @Override public void run() { - UserDetails userDetails; - try { - userDetails = mUserDetailsEndpoint.fetchUserDetails(userId); - } catch (NetworkErrorException e) { - notifyFailed(userId); - } - mUserDetailsCache.cacheUserDetails(userDetails); - notifySucceeded(userDetails); + fetchDataSync(); } }); } - private void notifySucceeded(final UserDetails userDetails) { - mUiThreadPoster.post(new Runnable() { - @Override - public void run() { - for (Listener listener : getListeners()) { - listener.onUserDetailsUpdated(userDetails); + @WorkerThread + private void fetchDataSync() { + try { + final String data = mFakeDataFetcher.getData(); + mUiThreadPoster.post(new Runnable() { // notify listeners on UI thread + @Override + public void run() { + notifySuccess(data); } - } - }); - } - - private void notifyFailed(final String userId) { - mUiThreadPoster.post(new Runnable() { - @Override - public void run() { - for (Listener listener : getListeners()) { - listener.onUserDetailsUpdateFailed(userId); + }); + } catch (FakeDataFetcher.DataFetchException e) { + mUiThreadPoster.post(new Runnable() { // notify listeners on UI thread + @Override + public void run() { + notifyFailure(); } - } - }); + }); + } + } -} -``` -## Install + @UiThread + private void notifyFailure() { + for (Listener listener : mListeners) { + listener.onDataFetchFailed(); + } + } -To use ThreadPoster in your project, add this line to your Gradle dependencies configuration: + @UiThread + private void notifySuccess(String data) { + for (Listener listener : mListeners) { + listener.onDataFetched(data); + } + } +} ``` -implementation 'com.techyourchance.threadposter:threadposter:0.8.0' -``` + ## License This project is licensed under the Apache-2.0 License - see the [LICENSE.txt](LICENSE.txt) file for details