Orange Cloud SDK for Android

LICENCE

Copyright (c) 2014 Orange.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Orange API : Register your app

At this time, the downloadable projects are designed for use with Gradle and Android Studio. If you haven't already, first follow the steps at Google's Android Studio installation guide.

First, you have to register your app on the Orange developer portal in order to get needed informations to identify your app (App Key, app Secret, redirect uri...).

Adding SDK to existing projects with JitPack.io

We use JitPack.io to deliver an Android library for Orange Cloud Sdk Android

Add it to your build.gradle with:

repositories {   
    jcenter()
    maven { url "https://jitpack.io" }
}

and:

dependencies {
    // Orange Cloud Android Sdk
    compile 'com.github.Orange-OpenSource:OrangeCloudAndroidSdk:1.0.7'
}

Sample app

Sample app is a very basic Android app that authenticates Orange user and then offers basic actions (browse, delete, create, rename, copy, move folder or files and upload files). You can import sample project into Android Studio by clicking in File > Import Projects... and select sample directory.

You'll need to edit the code to enter your app key, your app secret and redirect uri where indicated in the MainActivity.java file.

final static private String APP_KEY = "your client app key";
final static private String APP_SECRET = "your client app secret";
final static private String APP_REDIRECT_URI = "your client redirect uri";

Authenticating your app

You need to enter the following snippet in your AndroidManifest.xml in order to authenticate the Orange user. Insert the following code under the <application> section.

<activity
	android:name="com.orange.labs.sdk.activity.AuthActivity"
	android:launchMode="singleTask"
	android:configChanges="orientation|keyboard"/>

Make sure that your app has the internet permission. Insert the following code under the <manifest> section

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

In your Activity.java, you need to define contants get on Orange developer portal

final static private String APP_KEY = "your client app key";
final static private String APP_SECRET = "your client app secret";
final static private String APP_REDIRECT_URI = "your client redirect uri";

Pass all three values to the new OrangeCloudAPI object.

// In the class declaration section:
public OrangeCloudAPI<AuthSession> mApi;

// and for example, in onCreate function:
AuthSession session = new AuthSession(Activity.this, APP_KEY, APP_SECRET, APP_REDIRECT_URI);
mApi = new OrangeCloudAPI<AuthSession>(session);

Now, you can start authentication process. If it is the first connection for Orange user, method opens the AuthActivity declared in AndroidManifest.xml in order to authenticate user and authorize the access of Orange Cloud service.

mApi.getSession().startAuthentication();

Upon authentication, users are returned your own Activity.java. To finish authentication after the user returns to your app, you have to put the following code in your onResume function.

@Override
protected void onResume() {
	super.onResume();
	// Get the session and check the authentication state. 
	//!\ Have a asynchronous request here to check or refresh access token.
	final AuthSession session = mApi.getSession();
	session.checkAuthentication(new OrangeListener.Success<String>() {
		@Override
		public void onResponse(String response) {
			// Have a valid session, you can begin to use Cloud functions  
		}
	}, new OrangeListener.Error() {
		@Override
		public void onErrorResponse(OrangeAPIException error) {
			// An error occurred
		}
	});
}

Add scopes

Before to call mApi.getSession().startAuthentication();, you can add new scopes. For example, if you have access to Cloud Full Read API (see documentation on Cloud Api Reference), you can add this scope like :

// Add scope "cloudfullread"
mApi.addScope("cloudfullread");

// Start session
session.startAuthentication();

Listing contents

To list folder and contents, you have to pass an Entry object (nullto get the root). An entry is a representation of file or folder.

mApi.listEntries(anEntry, parameters, new OrangeListener.Success<OrangeCloudAPI.Entry>() {
	Override
	public void onResponse(OrangeCloudAPI.Entry response) {
		// success
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

parameters is an JSONObject parameters. You can enable pagination or other parameters (see Cloud Api Reference)

listContents() function returns just the unique identifier and name of files. If you want more informations about file, you have to call fileInfo() function to get the creation date, size and thumbnail and content URLs

mApi.fileInfo(fileEntry, new OrangeListener.Success<OrangeCloudAPI.Entry>() {
	@Override
	public void onResponse(OrangeCloudAPI.Entry entry) {
		// Returns the entry file with extra informations.
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

Create folder

Create a folder as a Entry child. Name of folder has to be unique. Returns an Entry folder

mApi.createFolder(anEntry, folderName, new OrangeListener.Success<OrangeCloudAPI.Entry>() {
	@Override
	public void onResponse(OrangeCloudAPI.Entry newFolder) {
		// folder has been created
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

Delete folder or file

You can delete a file or a folder and its contents by calling delete function.

mApi.delete(entryToRemove, new OrangeListener.Success<String>() {
	@Override
	public void onResponse(String response) {
		// File or folder entry has been deleted                   
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

Rename folder or file [new]

You can rename a file or a folder by calling rename function.

mApi.rename(entryToRename, name, new OrangeListener.Success<String>() {
	@Override
	public void onResponse(String response) {
		// File or folder entry has been deleted                   
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

Copy folder or file [new]

You can copy a file or a folder by calling copy function.

mApi.copy(entryToCopy, destination, new OrangeListener.Success<String>() {
	@Override
	public void onResponse(String response) {
		// File or folder entry has been deleted                   
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

Note: You can not copy a folder in the same parent.

Move folder or file [new]

You can copy a file or a folder by calling copy function.

mApi.copy(entryToCopy, destination, new OrangeListener.Success<String>() {
	@Override
	public void onResponse(String response) {
		// File or folder entry has been deleted                   
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

Note: You can not copy a folder in the same parent.

Upload a File

/!\ This function has to be called as a background task, for example an AsyncTask or maybe an IntentService.

mApi.upload(fileUri, filename, entryToUpload, new OrangeListener.Success<JSONObject>() {
	@Override
	public void onResponse(JSONObject response) {
		// File has been uploaded
	}
}, new OrangeListener.Progress() {
	@Override
	public void onProgress(float ratio) {
		// Listener to create progress bar (ratio = [0,1])
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

To get the File Object, you can use an Intent and get the result in the onActivityResult (See sample)

Intent intent = new Intent();
intent.setType("image/*");
intent.setAction(Intent.ACTION_GET_CONTENT);
startActivityForResult(Intent.createChooser(intent, "Select Picture"), 1);

File content features

SDK not offers basic methods to download and save file on the disk but you are able to develop thanks to Entry properties (thumbnailURL, previewURL, downloadURL) and getHeaders() from OrangeCloudAPI. /!\ Theses properties are available after a fileInfo request.

You can display easily the thumbnail of an entry file. It is a very small graphical representation of the file, only available for some file type (photo, pdf, ...)

mApi.thumbnail(entry, new OrangeListener.Success<Bitmap>() {
	@Override
	public void onResponse(Bitmap response) {
	    // Have a Bitmap            
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

You can display the preview of an entry file. It is a graphical representation suitable to be displayed in full screen on a mobile device, only available for some file type (photo, pdf, ...)

mApi.preview(entry, new OrangeListener.Success<Bitmap>() {
	@Override
	public void onResponse(Bitmap response) {
	    // Have a Bitmap            
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

Or display the real content of entry image.

mApi.imageContent(entry, new OrangeListener.Success<Bitmap>() {
	@Override
	public void onResponse(Bitmap response) {
	    // Have a Bitmap            
	}
}, new OrangeListener.Error() {
	@Override
	public void onErrorResponse(OrangeAPIException error) {
		// Error occurred
	}
});

Image cache policy

Methods thumbnail and preview can keep data in a cache. For that you have to declare a ImageCache thanks to Volley image cache just after to create Api object.

mApi = new OrangeCloudAPI<AuthSession>(session);
// An you can set a Image cache policy
mApi.setImageCache(new LruBitmapCache());

No newline at end of file