src/com/owncloud/android/operations/RemoteOperation.java

   1 /* ownCloud Android client application
   2  *   Copyright (C) 2012-2013 ownCloud Inc.
   3  *
   4  *   This program is free software: you can redistribute it and/or modify
   5  *   it under the terms of the GNU General Public License version 2,
   6  *   as published by the Free Software Foundation.
   7  *
   8  *   This program is distributed in the hope that it will be useful,
   9  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  *   GNU General Public License for more details.
  12  *
  13  *   You should have received a copy of the GNU General Public License
  14  *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
  15  *
  16  */
  17 package com.owncloud.android.operations;
  18
  19 import android.os.Handler;
  20
  21 import eu.alefzero.webdav.WebdavClient;
  22
  23 /**
  24  * Operation which execution involves one or several interactions with an ownCloud server.
  25  *
  26  * Provides methods to execute the operation both synchronously or asynchronously.
  27  *
  28  * @author David A. Velasco
  29  */
  30 public abstract class RemoteOperation implements Runnable {
  31
  32         /** Object to interact with the ownCloud server */
  33         private WebdavClient mClient = null;
  34
  35         /** Callback object to notify about the execution of the remote operation */
  36         private OnRemoteOperationListener mListener = null;
  37
  38         /** Handler to the thread where mListener methods will be called */
  39         private Handler mListenerHandler = null;
  40
  41
  42         /**
  43          *  Abstract method to implement the operation in derived classes.
  44          */
  45         protected abstract RemoteOperationResult run(WebdavClient client);
  46
  47
  48         /**
  49          * Synchronously executes the remote operation
  50          *
  51          * @param client        Client object to reach an ownCloud server during the execution of the operation.
  52          * @return                      Result of the operation.
  53          */
  54         public final RemoteOperationResult execute(WebdavClient client) {
  55                 if (client == null)
  56                         throw new IllegalArgumentException("Trying to execute a remote operation with a NULL WebdavClient");
  57                 mClient = client;
  58                 return run(client);
  59         }
  60
  61
  62         /**
  63          * Asynchronously executes the remote operation
  64          *
  65          * @param client                        Client object to reach an ownCloud server during the execution of the operation.
  66          * @param listener                      Listener to be notified about the execution of the operation.
  67          * @param listenerHandler       Handler associated to the thread where the methods of the listener objects must be called.
  68          * @return                                      Thread were the remote operation is executed.
  69          */
  70         public final Thread execute(WebdavClient client, OnRemoteOperationListener listener, Handler listenerHandler) {
  71                 if (client == null) {
  72                         throw new IllegalArgumentException("Trying to execute a remote operation with a NULL WebdavClient");
  73                 }
  74                 mClient = client;
  75
  76                 if (listener == null) {
  77                         throw new IllegalArgumentException("Trying to execute a remote operation asynchronously without a listener to notiy the result");
  78                 }
  79                 mListener = listener;
  80
  81                 if (listenerHandler == null) {
  82                         throw new IllegalArgumentException("Trying to execute a remote operation asynchronously without a handler to the listener's thread");
  83                 }
  84                 mListenerHandler = listenerHandler;
  85
  86                 Thread runnerThread = new Thread(this);
  87                 runnerThread.start();
  88                 return runnerThread;
  89         }
  90
  91     /**
  92      * Synchronously retries the remote operation using the same WebdavClient in the last call to {@link RemoteOperation#execute(WebdavClient)}
  93      *
  94      * @param listener          Listener to be notified about the execution of the operation.
  95      * @param listenerHandler   Handler associated to the thread where the methods of the listener objects must be called.
  96      * @return                  Thread were the remote operation is executed.
  97      */
  98     public final RemoteOperationResult retry() {
  99         return execute(mClient);
 100     }
 101
 102     /**
 103      * Asynchronously retries the remote operation using the same WebdavClient in the last call to {@link RemoteOperation#execute(WebdavClient, OnRemoteOperationListener, Handler)}
 104      *
 105      * @param listener          Listener to be notified about the execution of the operation.
 106      * @param listenerHandler   Handler associated to the thread where the methods of the listener objects must be called.
 107      * @return                  Thread were the remote operation is executed.
 108      */
 109     public final Thread retry(OnRemoteOperationListener listener, Handler listenerHandler) {
 110         return execute(mClient, listener, listenerHandler);
 111     }
 112
 113
 114         /**
 115          * Asynchronous execution of the operation
 116          * started by {@link RemoteOperation#execute(WebdavClient, OnRemoteOperationListener, Handler)},
 117          * and result posting.
 118          */
 119     @Override
 120     public final void run() {
 121         final RemoteOperationResult result = execute(mClient);
 122
 123         if (mListenerHandler != null && mListener != null) {
 124                 mListenerHandler.post(new Runnable() {
 125                 @Override
 126                 public void run() {
 127                     mListener.onRemoteOperationFinish(RemoteOperation.this, result);
 128                 }
 129             });
 130         }
 131     }
 132
 133
 134 }