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

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