IAndroidCSSManager.java

/**
Copyright (c) 2011, SOCIETIES Consortium (WATERFORD INSTITUTE OF TECHNOLOGY (TSSG), HERIOT-WATT UNIVERSITY (HWU), SOLUTA.NET 

(SN), GERMAN AEROSPACE CENTRE (Deutsches Zentrum fuer Luft- und Raumfahrt e.V.) (DLR), Zavod za varnostne tehnologije
informacijske družbe in elektronsko poslovanje (SETCCE), INSTITUTE OF COMMUNICATION AND COMPUTER SYSTEMS (ICCS), LAKE
COMMUNICATIONS (LAKE), INTEL PERFORMANCE LEARNING SOLUTIONS LTD (INTEL), PORTUGAL TELECOM INOVAÇÃO, SA (PTIN), IBM Corp (IBM),
INSTITUT TELECOM (ITSUD), AMITEC DIACHYTI EFYIA PLIROFORIKI KAI EPIKINONIES ETERIA PERIORISMENIS EFTHINIS (AMITEC), TELECOM 
ITALIA S.p.a.(TI), TRIALOG (TRIALOG), Stiftelsen SINTEF (SINTEF), NEC EUROPE LTD (NEC))
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package org.societies.android.api.internal.cssmanager;

import java.util.List;
import java.util.concurrent.Future;

import org.societies.api.schema.activity.MarshaledActivity;
import org.societies.api.schema.css.directory.CssAdvertisementRecord;
import org.societies.api.schema.cssmanagement.CssRecord;

/**
 * 
 * This interface forms the basis of the CSSManager, a component that will exist on all nodes. Its main tasks are:
 * 
 * 1. Allow a user to register or unregister a CSS
 * 2. Allow a user to login into a CSS
 * 3. Allow a user to logout out of a CSS
 * 3. Add and remove nodes that make up a CSS
 * 4. Get the current CSS profile
 * 5. Allow the status of a device to be changed
 * 6. Synchronise profile data
 * 7. Modify the CSS profile 
 * 8. Start all relevant Societies Android services
 * 
 * This interface will be implemented for android nodes. 
 *
 */

public interface IAndroidCSSManager {

	/**
	 * CSS Manager intents
	 * Used to create to create Intents to signal return values of a called method
	 * If the method is locally bound it is possible to directly return a value but is discouraged
	 * as called methods usually involve making asynchronous calls. 
	 */
	public static final String INTENT_RETURN_VALUE_KEY = "org.societies.android.platform.cssmanager.ReturnValue";
	public static final String INTENT_RETURN_STATUS_KEY = "org.societies.android.platform.cssmanager.ReturnStatus";

	public static final String CHANGE_CSS_NODE_STATUS = "org.societies.android.platform.cssmanager.CHANGE_CSS_NODE_STATUS";
	public static final String GET_ANDROID_CSS_RECORD = "org.societies.android.platform.cssmanager.GET_ANDROID_CSS_RECORD";
	public static final String LOGIN_CSS = "org.societies.android.platform.cssmanager.LOGIN_CSS";
	public static final String LOGIN_XMPP_SERVER = "org.societies.android.platform.cssmanager.LOGIN_XMPP_SERVER";
	public static final String LOGIN_XMPP_SERVER_EXCEPTION = "org.societies.android.platform.cssmanager.LOGIN_XMPP_SERVER_EXCEPTION";
	public static final String LOGOUT_CSS = "org.societies.android.platform.cssmanager.LOGOUT_CSS";
	public static final String LOGOUT_XMPP_SERVER = "org.societies.android.platform.cssmanager.LOGOUT_XMPP_SERVER";
	public static final String LOGOUT_XMPP_SERVER_EXCEPTION = "org.societies.android.platform.cssmanager.LOGOUT_XMPP_SERVER_EXCEPTION";
	public static final String MODIFY_ANDROID_CSS_RECORD = "org.societies.android.platform.cssmanager.MODIFY_ANDROID_CSS_RECORD";
	public static final String REGISTER_CSS = "org.societies.android.platform.cssmanager.REGISTER_CSS";
	public static final String REGISTER_CSS_DEVICE = "org.societies.android.platform.cssmanager.REGISTER_CSS_DEVICE";
	public static final String REGISTER_XMPP_SERVER = "org.societies.android.platform.cssmanager.REGISTER_XMPP_SERVER";
	public static final String REGISTER_XMPP_SERVER_EXCEPTION = "org.societies.android.platform.cssmanager.REGISTER_XMPP_SERVER_EXCEPTION";
	public static final String SET_PRESENCE_STATUS = "org.societies.android.platform.cssmanager.SET_PRESENCE_STATUS";
	public static final String SYNCH_PROFILE = "org.societies.android.platform.cssmanager.SYNCH_PROFILE";
	public static final String UNREGISTER_CSS = "org.societies.android.platform.cssmanager.UNREGISTER_CSS";
	public static final String UNREGISTER_CSS_DEVICE = "org.societies.android.platform.cssmanager.UNREGISTER_CSS_DEVICE";
	public static final String UNREGISTER_XMPP_SERVER = "org.societies.android.platform.cssmanager.UNREGISTER_XMPP_SERVER";
	public static final String START_APP_SERVICES = "org.societies.android.platform.cssmanager.START_APP_SERVICES";
	public static final String STOP_APP_SERVICES = "org.societies.android.platform.cssmanager.STOP_APP_SERVICES";
	public static final String GET_CSS_ACTIVITIES = "org.societies.android.platform.cssmanager.GET_CSS_ACTIVITIES";

	public static final String SUGGESTED_FRIENDS = "org.societies.android.platform.cssmanager.SUGGESTED_FRIENDS";
	public static final String GET_CSS_FRIENDS = "org.societies.android.platform.cssmanager.GET_CSS_FRIENDS";
	public static final String READ_PROFILE_REMOTE = "org.societies.android.platform.cssmanager.READ_PROFILE_REMOTE";
	public static final String SEND_FRIEND_REQUEST = "org.societies.android.platform.cssmanager.SEND_FRIEND_REQUEST";
	public static final String GET_FRIEND_REQUESTS = "org.societies.android.platform.cssmanager.GET_FRIEND_REQUESTS";
	public static final String ACCEPT_FRIEND_REQUEST = "org.societies.android.platform.cssmanager.ACCEPT_FRIEND_REQUEST";
	

	String methodsArray [] = {"registerXMPPServer(String client, AndroidCSSRecord profile)", //0
			"unregisterXMPPServer(String client, AndroidCSSRecord profile)",	//1
			"loginXMPPServer(String client, AndroidCSSRecord profile)",			//2
			"logoutXMPPServer(String client)",									//3
			"loginCSS(String client, AndroidCSSRecord profile)", 				//4
			"logoutCSS(String client, AndroidCSSRecord profile)",				//5
			"registerCSS(String client, AndroidCSSRecord profile)",				//6
			"unregisterCSS(String client, AndroidCSSRecord profile)",			//7
			"registerCSSDevice(String client, AndroidCSSRecord profile)",		//8
			"unregisterCSSDevice(String client, AndroidCSSRecord profile)",		//9
			"getAndroidCSSRecord(String client)",								//10
			"modifyAndroidCSSRecord(String client, AndroidCSSRecord profile)",	//11
			"changeCSSNodeStatus(String client, AndroidCSSRecord profile)", 	//12
			"synchProfile(String client, AndroidCSSRecord profile)",			//13
			"setPresenceStatus(String client, AndroidCSSRecord profile)",		//14
			"getCssFriends(String client)",										//15
			"getSuggestedFriends(String client)",								//16
			"readProfileRemote(String client, String cssId)",					//17
			"sendFriendRequest(String client, String cssId)",					//18
			"getFriendRequests(String client)",									//19
			"acceptFriendRequest(String client, String cssId)",					//20
			"startAppServices(String client)",									//21
			"stopAppServices(String client)",									//22
			"getActivities(String client, String timePeriod, int limitResults)" //23
	};
	
	/**
	 * Start all of the relevant Societies app services
	 * 
	 * @param client
	 */
	void startAppServices(String client);
	/**
	 * Stop all of the relevant Societies app services
	 * 
	 * @param client
	 */
	void stopAppServices(String client);
	/**
	 * Register with chosen Domain Server
	 * 
	 * @param client component package calling method
	 * @param profile
	 */
	void registerXMPPServer(String client, CssRecord profile);
	/**
	 * Unregister with chosen Domain Server
	 * 
	 * @param client component package calling method
	 * @param profile
	 */
	void unregisterXMPPServer(String client, CssRecord profile);
	/**
	 * Login with chosen Domain server
	 * 
	 * @param client component package calling method
	 * @param profile
	 */
	void loginXMPPServer(String client, CssRecord profile);
	/**
	 * Logout from chosen Domain server
	 * 
	 * @param client component package calling method
	 * @param profile
	 */
	void logoutXMPPServer(String client);

	
	/**
	 * Login a user to a CSS. The registration of devices included in the profile
	 * is implied.
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord loginCSS(String client, CssRecord profile);	

	/**
	 * Logout the user from a CSS
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord logoutCSS(String client, CssRecord profile);	
	
	/**
	 * Register a CSS
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord registerCSS(String client, CssRecord profile);

	/**
	 * Unregister the CSS
	 * TODO Is a CSS deleted or made inactive
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord unregisterCSS(String client, CssRecord profile);

	/**
	 * Register a device(s) with a CSS
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord registerCSSDevice(String client, CssRecord profile);
	/**
	 * Unregister a device(s) from a CSS
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord unregisterCSSDevice(String client, CssRecord profile);
	
	/**
	 * Get the CSS Profile. This operation will retrieve the local CSS Profile. 
	 * If none exists or the local cache is deemed to have expired this will 
	 * result in a synchronisation with the cloud node. 
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord getAndroidCSSRecord(String client);

	/**
	 * Modify the CSS Profile
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord modifyAndroidCSSRecord(String client, CssRecord profile);
	/**
	 * Change the status a CSS device
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord changeCSSNodeStatus(String client, CssRecord profile);
	
	/**
	 * Synchronise the CSS profile. The CSS cloud node's current profile is synchronised
	 * with the local device's cached version
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord synchProfile(String client, CssRecord profile);
	
	/**
	 * Set the presence status of the user
	 * 
	 * @param client component package calling method
	 * @param profile
	 * @return AndroidCSSRecord
	 */
	CssRecord setPresenceStatus(String client, CssRecord profile);
	
	/**
	 * Get friend CSS(s) advertisements
	 * @param client
	 * @return
	 */
	List<CssAdvertisementRecord> getCssFriends(String client);

	/**
	 * Get friend CSS(s) advertisements
	 * @param client
	 * @return
	 */
	List<CssAdvertisementRecord> getSuggestedFriends(String client);
	/**
	 * Get a friend's CSS profile
	 * 
	 * @param client
	 * @param cssId
	 * @return AndroidCSSRecord profile
	 */
	CssRecord readProfileRemote(String client, String cssId);

	/**
	 * TODO: what is return type ?
	 * @param client
	 * @param cssId
	 */
	void sendFriendRequest(String client, String cssId);
	
	/**
	 * Returns a list of Friend requests
	 * @param client
	 * @return
	 */
	CssAdvertisementRecord[] getFriendRequests(String client);
	
	/**
	 * Accepts Friend request
	 * @param client
	 * @param cssId
	 * @return
	 */
	void acceptFriendRequest(String client, String cssId);
	
	/**
	 * Retrieves activities for the user's CSS
	 * @param timePeriod Space delimited longs eg, "126423013000 1364230131045"
	 * @param limitResults number of records to limit to
	 * @return
	 */
	MarshaledActivity[] getActivities(String client, String timePeriod, int limitResults);
}