commenting, commenting, commenting!

.gitignore

@@ -19,6 +19,7 @@ oc_workaround/local.properties
 oc_framework/local.properties
 oc_framework-test-project/local.properties
 tests/local.properties
+lint.xml
 
 # Mac .DS_Store files
 .DS_Store

src/com/owncloud/android/MainApp.java

@@ -106,7 +106,9 @@ public class MainApp extends Application {
         return getAppContext().getResources().getString(R.string.db_name);
     }
      
-    //  data_folder
+    /**
+     * name of data_folder, e.g., "owncloud"
+     */
     public static String getDataFolder() {
         return getAppContext().getResources().getString(R.string.data_folder);
     }

src/com/owncloud/android/datamodel/OCFile.java

@@ -198,7 +198,7 @@ public class OCFile implements Parcelable, Comparable<OCFile> {
     }
 
     /**
-     * Can be used to set the path where the file is stored
+     * Can be used to set the path where the local file is stored
      * 
      * @param storage_path to set
      */

src/com/owncloud/android/db/UploadDbObject.java

@@ -6,17 +6,13 @@ import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.Serializable;
 
-import android.os.Parcel;
-import android.os.Parcelable;
 import android.util.Base64;
-import android.util.Log;
 
 import com.owncloud.android.db.UploadDbHandler.UploadStatus;
 import com.owncloud.android.files.services.FileUploadService.LocalBehaviour;
 import com.owncloud.android.lib.common.operations.RemoteOperationResult;
 import com.owncloud.android.lib.common.utils.Log_OC;
 
-
 /**
  * Stores all information in order to start upload. PersistentUploadObject can
  * be stored persistently by {@link UploadDbHandler}.
@@ -24,11 +20,12 @@ import com.owncloud.android.lib.common.utils.Log_OC;
  * @author LukeOwncloud
  * 
  */
-public class UploadDbObject  implements Serializable{
+public class UploadDbObject implements Serializable {
 
-    /** Generated - should be refreshed every time the class changes!! */;
+    /** Generated - should be refreshed every time the class changes!! */
+    ;
     private static final long serialVersionUID = -2306246191385279924L;
-    
+
     private static final String TAG = "UploadDbObject";
     /**
      * Local path to file which is to be uploaded.
@@ -47,6 +44,7 @@ public class UploadDbObject  implements Serializable{
      * Local action for upload.
      */
     LocalBehaviour localAction;
+
     /**
      * @return the uploadStatus
      */
@@ -91,12 +89,12 @@ public class UploadDbObject  implements Serializable{
      * Name of Owncloud account to upload file to.
      */
     String accountName;
-    
+
     /**
      * Status of upload (later, in_progress, ...).
      */
     UploadStatus uploadStatus;
-    
+
     /**
      * Result from last upload operation. Can be null.
      */
@@ -148,7 +146,7 @@ public class UploadDbObject  implements Serializable{
      * @return the localAction
      */
     public LocalBehaviour getLocalAction() {
-//        return null;
+        // return null;
         return localAction;
     }
 
@@ -214,13 +212,13 @@ public class UploadDbObject  implements Serializable{
     public void setAccountName(String accountName) {
         this.accountName = accountName;
     }
-    
+
     /**
      * Returns a base64 encoded serialized string of this object.
      */
     @Override
     public String toString() {
-     // serialize the object
+        // serialize the object
         try {
             ByteArrayOutputStream bo = new ByteArrayOutputStream();
             ObjectOutputStream so = new ObjectOutputStream(bo);
@@ -233,18 +231,6 @@ public class UploadDbObject  implements Serializable{
         } catch (Exception e) {
             Log_OC.e(TAG, "Cannot serialize UploadDbObject with localPath:" + getLocalPath(), e);
         }
-//        
-//        try {
-//            ByteArrayOutputStream bo = new ByteArrayOutputStream();
-//            ObjectOutputStream so = new ObjectOutputStream(bo);
-//            so.writeObject(this);
-//            so.flush();
-//            String base64 = Base64.encodeToString(bo.toString()
-//                    .getBytes(), Base64.DEFAULT);
-//            return base64;
-//        } catch (Exception e) {
-//            System.out.println(e);
-//        }
         return null;
     }
 
@@ -256,30 +242,17 @@ public class UploadDbObject  implements Serializable{
      * @return
      */
     static public UploadDbObject fromString(String serializedObjectBase64) {
-     // deserialize the object
+        // deserialize the object
         try {
             byte[] b = Base64.decode(serializedObjectBase64, Base64.DEFAULT);
             ByteArrayInputStream bi = new ByteArrayInputStream(b);
             ObjectInputStream si = new ObjectInputStream(bi);
             UploadDbObject obj = (UploadDbObject) si.readObject();
-            Log.e(TAG, "SUCCESS!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!");
             return obj;
         } catch (Exception e) {
             Log_OC.e(TAG, "Cannot deserialize UploadDbObject " + serializedObjectBase64, e);
         }
-//        try {
-//            byte b[] = Base64.decode(serializedObject, Base64.DEFAULT);
-//            ByteArrayInputStream bi = new ByteArrayInputStream(b);
-//            ObjectInputStream si = new ObjectInputStream(bi);
-//            return (UploadDbObject) si.readObject();
-//        } catch (Exception e) {
-//            Log_OC.e(TAG, "Cannot deserialize UploadDbObject " + serializedObject, e);
-//        }
         return null;
     }
 
-
-
 }
-
-

src/com/owncloud/android/files/services/FileUploadService.java

@@ -18,12 +18,8 @@
 
 package com.owncloud.android.files.services;
 
-import java.io.ByteArrayInputStream;
-import java.io.ByteArrayOutputStream;
 import java.io.File;
 import java.io.IOException;
-import java.io.ObjectInputStream;
-import java.io.ObjectOutputStream;
 import java.util.AbstractList;
 import java.util.Date;
 import java.util.HashMap;
@@ -52,8 +48,6 @@ import android.os.Looper;
 import android.os.Message;
 import android.os.Process;
 import android.support.v4.app.NotificationCompat;
-import android.util.Base64;
-import android.util.Log;
 import android.webkit.MimeTypeMap;
 
 import com.owncloud.android.R;
@@ -93,6 +87,7 @@ import com.owncloud.android.utils.ErrorMessageAdapter;
  * @author LukeOwncloud
  * 
  */
+@SuppressWarnings("unused")
 public class FileUploadService extends Service {
 
     private static final String UPLOAD_FINISH_MESSAGE = "UPLOAD_FINISH";
@@ -119,7 +114,22 @@ public class FileUploadService extends Service {
      * Describes local behavior for upload.
      */
     public enum LocalBehaviour {
-        LOCAL_BEHAVIOUR_COPY(0), LOCAL_BEHAVIOUR_MOVE(1), LOCAL_BEHAVIOUR_FORGET(2);
+        /**
+         * Creates a copy of file and stores it in tmp folder inside owncloud
+         * folder on sd-card. After upload it is moved to local owncloud
+         * storage. Original file stays untouched.
+         */
+        LOCAL_BEHAVIOUR_COPY(0),
+        /**
+         * Upload file from current storage. Afterwards original file is move to
+         * local owncloud storage.
+         */
+        LOCAL_BEHAVIOUR_MOVE(1),
+        /**
+         * Just uploads file and leaves it where it is. Original file stays
+         * untouched.
+         */
+        LOCAL_BEHAVIOUR_FORGET(2);
         private final int value;
 
         private LocalBehaviour(int value) {
@@ -183,6 +193,7 @@ public class FileUploadService extends Service {
         return account.name + file.getRemotePath();
     }
 
+    
     private String buildRemoteName(Account account, String remotePath) {
         return account.name + remotePath;
     }
@@ -279,7 +290,6 @@ public class FileUploadService extends Service {
                 if (uploadType == UploadSingleMulti.UPLOAD_SINGLE_FILE) {
                     files = new OCFile[] { intent.getParcelableExtra(KEY_FILE) };
                 } else {
-                    // TODO will this casting work fine?
                     files = (OCFile[]) intent.getParcelableArrayExtra(KEY_FILE);
                 }
 
@@ -532,53 +542,53 @@ public class FileUploadService extends Service {
      */
     private void uploadFile(UploadDbObject uploadDbObject) {
 
-     // AccountManager aMgr = AccountManager.get(this);
-        // String version = aMgr.getUserData(account,
-        // Constants.KEY_OC_VERSION);
-        // OwnCloudVersion ocv = new OwnCloudVersion(version);
-        //
-        // boolean chunked =
-        // FileUploadService.chunkedUploadIsSupported(ocv);
-        // AbstractList<String> requestedUploads = new Vector<String>();
-        // String uploadKey = null;
-        // UploadFileOperation newUpload = null;
-        // try {
-        // for (int i = 0; i < files.length; i++) {
-        // uploadKey = buildRemoteName(account, files[i].getRemotePath());
+//      AccountManager aMgr = AccountManager.get(this);
+//         String version = aMgr.getUserData(account,
+//         Constants.KEY_OC_VERSION);
+//         OwnCloudVersion ocv = new OwnCloudVersion(version);
+//        
+//         boolean chunked =
+//         FileUploadService.chunkedUploadIsSupported(ocv);
+//         AbstractList<String> requestedUploads = new Vector<String>();
+//         String uploadKey = null;
+//         UploadFileOperation newUpload = null;
+//         try {
+//         for (int i = 0; i < files.length; i++) {
+//         uploadKey = buildRemoteName(account, files[i].getRemotePath());
 //         newUpload = new UploadFileOperation(account, files[i], chunked,
-        // forceOverwrite, localAction,
-        // getApplicationContext());
-        // if (isCreateRemoteFolder) {
-        // newUpload.setRemoteFolderToBeCreated();
-        // }
-        // mActiveUploads.putIfAbsent(uploadKey, newUpload); // Grants that
-        // the file only upload once time
-        //
-        // newUpload.addDatatransferProgressListener((FileUploaderBinder)mBinder);
-        // requestedUploads.add(uploadKey);
-        // }
-        //
-        // } catch (IllegalArgumentException e) {
-        // Log_OC.e(TAG, "Not enough information provided in intent: " +
-        // e.getMessage());
-        // return START_NOT_STICKY;
-        //
-        // } catch (IllegalStateException e) {
-        // Log_OC.e(TAG, "Bad information provided in intent: " +
-        // e.getMessage());
-        // return START_NOT_STICKY;
-        //
-        // } catch (Exception e) {
-        // Log_OC.e(TAG,
-        // "Unexpected exception while processing upload intent", e);
-        // return START_NOT_STICKY;
-        //
-        // }
+//         forceOverwrite, localAction,
+//         getApplicationContext());
+//         if (isCreateRemoteFolder) {
+//         newUpload.setRemoteFolderToBeCreated();
+//         }
+//         mActiveUploads.putIfAbsent(uploadKey, newUpload); // Grants that
+//         the file only upload once time
+//        
+//         newUpload.addDatatransferProgressListener((FileUploaderBinder)mBinder);
+//         requestedUploads.add(uploadKey);
+//         }
+//        
+//         } catch (IllegalArgumentException e) {
+//         Log_OC.e(TAG, "Not enough information provided in intent: " +
+//         e.getMessage());
+//         return START_NOT_STICKY;
+//        
+//         } catch (IllegalStateException e) {
+//         Log_OC.e(TAG, "Bad information provided in intent: " +
+//         e.getMessage());
+//         return START_NOT_STICKY;
+//        
+//         } catch (Exception e) {
+//         Log_OC.e(TAG,
+//         "Unexpected exception while processing upload intent", e);
+//         return START_NOT_STICKY;
+//        
+//         }
         
         synchronized (mActiveUploads) {
             mCurrentUpload = mActiveUploads.get(uploadDbObject.getRemotePath());
             
-            //TODO: add object here, to make thread-safe
+            //TODO: add object to mCurrentUpload here, to make thread-safe
             //mActiveUploads.putIfAbsent(uploadKey, newUpload); // Grants that
         }
 

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

@@ -62,7 +62,14 @@ public class UploadFileOperation extends RemoteOperation {
     private static final String TAG = UploadFileOperation.class.getSimpleName();
 
     private Account mAccount;
+    /**
+     * OCFile which is to be uploaded.
+     */
     private OCFile mFile;
+    /**
+     * Original OCFile which is to be uploaded in case file had to be renamed
+     * (if forceOverwrite==false and remote file already exists).
+     */
     private OCFile mOldFile;
     private String mRemotePath = null;
     private boolean mChunked = false;
@@ -71,6 +78,9 @@ public class UploadFileOperation extends RemoteOperation {
     private LocalBehaviour mLocalBehaviour = FileUploadService.LocalBehaviour.LOCAL_BEHAVIOUR_COPY;
     private boolean mWasRenamed = false;
     private String mOriginalFileName = null;
+    /**
+     * Local path to file which is to be uploaded (before any possible renaming or moving).
+     */
     private String mOriginalStoragePath = null;
     PutMethod mPutMethod = null;
     private Set<OnDatatransferProgressListener> mDataTransferListeners = new HashSet<OnDatatransferProgressListener>();
@@ -122,6 +132,10 @@ public class UploadFileOperation extends RemoteOperation {
         return mFile;
     }
 
+    /**
+     * If remote file was renamed, return original OCFile which was uploaded. Is
+     * null is file was not renamed.
+     */
     public OCFile getOldFile() {
         return mOldFile;
     }
@@ -205,7 +219,8 @@ public class UploadFileOperation extends RemoteOperation {
 
             // check location of local file; if not the expected, copy to a
             // temporal file before upload (if COPY is the expected behaviour)
-            if (!mOriginalStoragePath.equals(expectedPath) && mLocalBehaviour == FileUploadService.LocalBehaviour.LOCAL_BEHAVIOUR_COPY) {
+            if (!mOriginalStoragePath.equals(expectedPath)
+                    && mLocalBehaviour == FileUploadService.LocalBehaviour.LOCAL_BEHAVIOUR_COPY) {
 
                 if (FileStorageUtils.getUsableSpace(mAccount.name) < originalFile.length()) {
                     result = new RemoteOperationResult(ResultCode.LOCAL_STORAGE_FULL);
@@ -346,6 +361,11 @@ public class UploadFileOperation extends RemoteOperation {
         return result;
     }
 
+    /**
+     * Create a new OCFile mFile with new remote path. This is required if forceOverwrite==false.
+     * New file is stored as mFile, original as mOldFile. 
+     * @param newRemotePath new remote path
+     */
     private void createNewOCFile(String newRemotePath) {
         // a new OCFile instance must be created for a new remote path
         OCFile newFile = new OCFile(newRemotePath);

src/com/owncloud/android/ui/activity/UploadFilesActivity.java

@@ -34,23 +34,24 @@ import android.widget.TextView;
 
 import com.actionbarsherlock.app.ActionBar;
 import com.actionbarsherlock.app.ActionBar.OnNavigationListener;
-import com.actionbarsherlock.internal.view.menu.ActionMenuItemView;
 import com.actionbarsherlock.view.Menu;
 import com.actionbarsherlock.view.MenuInflater;
 import com.actionbarsherlock.view.MenuItem;
 import com.owncloud.android.R;
 import com.owncloud.android.lib.common.utils.Log_OC;
 import com.owncloud.android.ui.dialog.ConfirmationDialogFragment;
-import com.owncloud.android.ui.dialog.IndeterminateProgressDialog;
 import com.owncloud.android.ui.dialog.ConfirmationDialogFragment.ConfirmationDialogFragmentListener;
+import com.owncloud.android.ui.dialog.IndeterminateProgressDialog;
 import com.owncloud.android.ui.fragment.LocalFileListFragment;
 import com.owncloud.android.utils.DisplayUtils;
 import com.owncloud.android.utils.FileStorageUtils;
 
 
 /**
- * Displays local files and let the user choose what of them wants to upload
- * to the current ownCloud account
+ * Displays local files and let the user choose which file to upload to the
+ * current ownCloud account. Selected files are sent back to the caller as Extra
+ * named EXTRA_CHOSEN_FILES. Thus, thus activity does not perform the upload
+ * itself. (It should thus be renamed to FileUploadChooserActivity or something)
  * 
  * @author David A. Velasco
  * 

src/com/owncloud/android/ui/activity/Uploader.java

@@ -25,7 +25,6 @@ import java.util.LinkedList;
 import java.util.List;
 import java.util.Stack;
 import java.util.Vector;
-
 import com.owncloud.android.MainApp;
 import com.owncloud.android.R;
 import com.owncloud.android.authentication.AccountAuthenticator;
@@ -33,9 +32,9 @@ import com.owncloud.android.datamodel.FileDataStorageManager;
 import com.owncloud.android.datamodel.OCFile;
 import com.owncloud.android.files.services.FileUploadService;
 import com.owncloud.android.lib.common.utils.Log_OC;
-
 import android.accounts.Account;
 import android.accounts.AccountManager;
+import android.annotation.SuppressLint;
 import android.app.AlertDialog;
 import android.app.AlertDialog.Builder;
 import android.app.Dialog;
@@ -61,14 +60,15 @@ import android.widget.Button;
 import android.widget.EditText;
 import android.widget.SimpleAdapter;
 import android.widget.Toast;
-
 import com.actionbarsherlock.app.ActionBar;
 import com.actionbarsherlock.app.SherlockListActivity;
 import com.actionbarsherlock.view.MenuItem;
 import com.owncloud.android.utils.DisplayUtils;
 
 /**
- * This can be used to upload things to an ownCloud instance.
+ * This class is registered for Intents android.intent.action.SEND and android.intent.action.SEND_MULTIPLE
+ * and causes indicated to be uploaded to an ownCloud instance. User can choose which account to use as well
+ * as the upload destination.
  * 
  * @author Bartek Przybylski
  * 
@@ -355,7 +355,8 @@ public class Uploader extends SherlockListActivity implements OnItemClickListene
         return (mStreamsToUpload != null && mStreamsToUpload.get(0) != null);
     }
 
-    public void uploadFiles() {
+    @SuppressLint("NewApi")
+	public void uploadFiles() {
         try {
 
             ArrayList<String> local = new ArrayList<String>();

src/com/owncloud/android/utils/FileStorageUtils.java

@@ -41,22 +41,38 @@ import android.os.StatFs;
 public class FileStorageUtils {
     //private static final String LOG_TAG = "FileStorageUtils";
 
+    /**
+     * Get local owncloud storage path for accountName.
+     */
     public static final String getSavePath(String accountName) {
         File sdCard = Environment.getExternalStorageDirectory();
         return sdCard.getAbsolutePath() + "/" + MainApp.getDataFolder() + "/" + Uri.encode(accountName, "@");
         // URL encoding is an 'easy fix' to overcome that NTFS and FAT32 don't allow ":" in file names, that can be in the accountName since 0.1.190B
     }
 
+    /**
+     * Get local path where OCFile file is to be stored after upload. That is,
+     * corresponding local path (in local owncloud storage) to remote uploaded
+     * file.
+     */
     public static final String getDefaultSavePathFor(String accountName, OCFile file) {
         return getSavePath(accountName) + file.getRemotePath();
     }
 
+    /**
+     * Get absolute path to tmp folder inside datafolder in sd-card for given accountName.
+     */
     public static final String getTemporalPath(String accountName) {
         File sdCard = Environment.getExternalStorageDirectory();
         return sdCard.getAbsolutePath() + "/" + MainApp.getDataFolder() + "/tmp/" + Uri.encode(accountName, "@");
             // URL encoding is an 'easy fix' to overcome that NTFS and FAT32 don't allow ":" in file names, that can be in the accountName since 0.1.190B
     }
 
+    /**
+     * Optimistic number of bytes available on sd-card. accountName is ignored.
+     * @param accountName not used. can thus be null.
+     * @return Optimistic number of available bytes (can be less)
+     */
     @SuppressLint("NewApi")
     public static final long getUsableSpace(String accountName) {
         File savePath = Environment.getExternalStorageDirectory();