Merge pull request #19 from nhaarman/master

Simpler & Testable API

Author: nhaarman

README.md

@@ -1,4 +1,4 @@
-# AsyncTask-Android
+# AsyncTask-Android [ ![Download](https://api.bintray.com/packages/label305/Label305/AsyncTask-Android/images/download.svg) ](https://bintray.com/label305/Label305/AsyncTask-Android/_latestVersion)
 
 AsyncTask made simpler.
 
@@ -18,7 +18,7 @@ Use a `SimpleAsyncTask` when doing work that will not throw a checked `Exception
 public class MyAsyncTask extends SimpleAsyncTask<String> {
 
   @Override
-  protected String doInBackgroundSimple() {
+  protected String doInBackground() {
     return "Test";
   }
 
@@ -50,7 +50,105 @@ public class MyAsyncTask extends AsyncTask<String, IOException> {
   protected void onException(final IOException e) {
     // Handle IOException
   }
+}
+```
+
+## Executing
+
+Like Android's `AsyncTask`, you can call `execute()` on the `AsyncTask` instance to start it:
+
+```java
+new MyAsyncTask().execute();
+```
+
+Alternatively, you can use an [`AsyncTaskExecutor`](https://github.com/Label305/AsyncTask-Android/blob/master/asynctask/src/main/java/com/label305/asynctask/AsyncTaskExecutor.java)
+to delegate the execution. A default implementation is available as `AsyncTaskExecutor.DEFAULT_EXECUTOR`, which is used by `AsyncTask.execute()`.
+
+```java
+AsyncTaskExecutor.DEFAULT_EXECUTOR.execute(new MyAsyncTask());
+```
+
+## Testing
+
+The `AsyncTaskExecutor` can come in handy while testing. When practicing dependency injection, you can inject a different implementation that executes the
+`AsyncTask` synchronously. [TestAsyncTaskExecutor](https://github.com/Label305/AsyncTask-Android/blob/master/asynctask-test/src/main/java/com/label305/asynctask/TestAsyncTaskExecutor.java)
+can be used for such tests. To access this class, add the following to your relevant `build.gradle` section:
+
+```groovy
+testCompile 'com.label305:asynctask-test:x.x.x' // For unit tests
+androidTestCompile 'com.label305:asynctask-test:x.x.x' // For instrumentation tests
+```
+
+For example, suppose we have the following class for asynchronously retrieving a `User` from some web service:
+
+```java
+public class UserRetriever {
+
+  private final WebService mWebService;
+
+  private final AsyncTaskExecutor mExecutor;
+
+  public UserRetriever(final WebService webService, final AsyncTaskExecutor executor) {
+    mWebService = webService;
+    mExecutor = executor;
+  }
 
+  /**
+   * Retrieves the User asynchronously, and notifies given callback when the User is retrieved.
+   */
+  public void retrieveUser(final UserCallback callback) {
+    mExecutor.execute(new RetrieveUserTask(callback));
+  }
+
+  public interface UserCallback {
+
+    void onUserRetrieved(User user);
+  }
+
+  private class RetrieveUserTask extends SimpleAsyncTask<User> {
+
+    private final UserCallback mCallback;
+
+    private RetrieveUserTask(final UserCallback callback) {
+      mCallback = callback;
+    }
+
+    @Override
+    public User doInBackground() {
+      return mWebService.retrieveUser();
+    }
+
+    @Override
+    public void onSuccess(final User user) {
+      mCallback.onUserRetrieved(user);
+    }
+  }
+}
+```
+
+We can test this class using mock objects, in this case Mockito:
+
+```java
+public class UserRetrieverTest {
+
+  @Test
+  public void retrieveUser_retrievesUser_andNotifiesCallback() {
+    /* Given */
+    User user = new User();
+
+    WebService webService = mock(WebService.class);
+    when(webService.retrieveUser()).thenReturn(user);
+
+    UserCallback callback = mock(UserCallback.class);
+
+    UserRetriever userRetriever = new UserRetriever(webService, TestAsyncTaskExecutor.instance());
+
+    /* When */
+    userRetriever.retrieveUser(callback);
+
+    /* Then */
+    verify(callback).onUserRetrieved(user);
+  }
 }
 ```
 

RELEASING.md

@@ -0,0 +1,16 @@
+apply plugin: 'com.android.library'
+
+apply from: rootProject.projectDir.absolutePath + '/gradle/compile.gradle'
+apply from: rootProject.projectDir.absolutePath + '/gradle/publishing.gradle'
+apply from: rootProject.projectDir.absolutePath + '/gradle/bintray.gradle'
+apply from: rootProject.projectDir.absolutePath + '/gradle/artifactory.gradle'
+
+dependencies {
+  compile project(':asynctask')
+
+  provided 'com.android.support:support-annotations:22.2.1'
+
+  testCompile project(':asynctask-test')
+  testCompile 'junit:junit:4.12'
+  testCompile 'org.mockito:mockito-core:2.0.31-beta'
+}

asynctask-example/build.gradle

@@ -0,0 +1,3 @@
+POM_NAME=AsyncTask Example
+POM_ARTIFACT_ID=asynctask-example
+POM_PACKAGING=aar

asynctask-example/gradle.properties

@@ -0,0 +1 @@
+<manifest package="com.label305.asynctask.example" />

asynctask-example/src/main/AndroidManifest.xml

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2015 Label305
+ *
+ * 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.
+ */
+
+package com.label305.asynctask.example;
+
+public class User {
+}

asynctask-example/src/main/java/com/label305/asynctask/example/User.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2015 Label305
+ *
+ * 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.
+ */
+
+package com.label305.asynctask.example;
+
+import android.support.annotation.NonNull;
+import com.label305.asynctask.AsyncTask;
+import com.label305.asynctask.AsyncTaskExecutor;
+import java.io.IOException;
+
+public class UserRetriever {
+
+  private final WebService mWebService;
+
+  private final AsyncTaskExecutor mExecutor;
+
+  public UserRetriever(final WebService webService, final AsyncTaskExecutor executor) {
+    mWebService = webService;
+    mExecutor = executor;
+  }
+
+  /**
+   * Retrieves the User asynchronously, and notifies given callback when the User is retrieved.
+   */
+  public void retrieveUser(final UserCallback callback) {
+    mExecutor.execute(new RetrieveUserTask(callback));
+  }
+
+  public interface UserCallback {
+
+    void onUserRetrieved(User user);
+
+    void onException(IOException e);
+  }
+
+  private class RetrieveUserTask extends AsyncTask<User, IOException> {
+
+    private final UserCallback mCallback;
+
+    private RetrieveUserTask(final UserCallback callback) {
+      mCallback = callback;
+    }
+
+    @Override
+    public User doInBackground() throws IOException {
+      return mWebService.retrieveUser();
+    }
+
+    @Override
+    public void onSuccess(final User user) {
+      mCallback.onUserRetrieved(user);
+    }
+
+    @Override
+    protected void onException(@NonNull final IOException e) {
+      mCallback.onException(e);
+    }
+  }
+}

asynctask-example/src/main/java/com/label305/asynctask/example/UserRetriever.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2015 Label305
+ *
+ * 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.
+ */
+
+package com.label305.asynctask.example;
+
+import java.io.IOException;
+
+public interface WebService {
+
+  User retrieveUser() throws IOException;
+}

asynctask-example/src/main/java/com/label305/asynctask/example/WebService.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2015 Label305
+ *
+ * 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.
+ */
+
+package com.label305.asynctask.example;
+
+import com.label305.asynctask.TestAsyncTaskExecutor;
+import java.io.IOException;
+import org.junit.Test;
+
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@SuppressWarnings("NewExceptionWithoutArguments")
+public class UserRetrieverTest {
+
+  @Test
+  public void retrieveUser_retrievesUser_andNotifiesCallback() throws IOException {
+    /* Given */
+    User user = new User();
+
+    WebService webService = mock(WebService.class);
+    when(webService.retrieveUser()).thenReturn(user);
+
+    UserRetriever.UserCallback callback = mock(UserRetriever.UserCallback.class);
+
+    UserRetriever userRetriever = new UserRetriever(webService, TestAsyncTaskExecutor.instance());
+
+    /* When */
+    userRetriever.retrieveUser(callback);
+
+    /* Then */
+    verify(callback).onUserRetrieved(user);
+  }
+
+  @Test
+  public void retrieveUser_retrievesUser_withException_notifiesCallback() throws IOException {
+    /* Given */
+    IOException e = new IOException();
+
+    WebService webService = mock(WebService.class);
+    when(webService.retrieveUser()).thenThrow(e);
+
+    UserRetriever.UserCallback callback = mock(UserRetriever.UserCallback.class);
+
+    UserRetriever userRetriever = new UserRetriever(webService, TestAsyncTaskExecutor.instance());
+
+    /* When */
+    userRetriever.retrieveUser(callback);
+
+    /* Then */
+    verify(callback).onException(e);
+  }
+}

asynctask-example/src/test/java/com/label305/asynctask/example/UserRetrieverTest.java

@@ -0,0 +1,19 @@
+apply plugin: 'com.android.library'
+
+android {
+  lintOptions {
+    disable 'InvalidPackage'
+  }
+}
+
+apply from: rootProject.projectDir.absolutePath + '/gradle/compile.gradle'
+apply from: rootProject.projectDir.absolutePath + '/gradle/publishing.gradle'
+apply from: rootProject.projectDir.absolutePath + '/gradle/bintray.gradle'
+apply from: rootProject.projectDir.absolutePath + '/gradle/artifactory.gradle'
+
+dependencies {
+  compile project(':asynctask')
+  compile 'org.mockito:mockito-core:2.0.31-beta'
+
+  provided 'com.android.support:support-annotations:22.2.1'
+}