IServices.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., 
 * 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.api.services;


import java.util.List;

import org.societies.api.cis.management.ICis;
import org.societies.api.identity.IIdentity;
import org.societies.api.schema.servicelifecycle.model.ServiceResourceIdentifier;

/**
 * This interface may be used by a third-party service to obtain information on itself from the platform
 *
 * @author <a href="mailto:sanchocsa@gmail.com">Sancho Rêgo</a> (PTIN)
 *
 */
public interface IServices {
	
	/**
	 * This method allows a third-party service to get its own ServiceResourceIdentifier by passing a reference to itself.
	 * Note that it only works after the service is fully started, so shouldn't be used in "init" methods of the bean.
	 * 
	 * @param callingClass (i.e., "this")
	 * @return the service resource identifier of the service
	 */
	public ServiceResourceIdentifier getMyServiceId(java.lang.Class<?> callingClass);
	
	/**
	 * This method allows a service to retrieve its own name
	 * 
	 * @param serviceId
	 * @return the name of the service
	 */
	public String getMyName(ServiceResourceIdentifier serviceId);

	/**
	 * This method allows a service to retrieve its version
	 * 
	 * @param serviceId
	 * @return the service version
	 */
	public String getMyVersion(ServiceResourceIdentifier serviceId);
	
	/**
	 * This method is used by a third-party client service to get the node of its parent/server
	 * 
	 * @param serviceId
	 * @return the node of the parent
	 */
	public IIdentity getServer(ServiceResourceIdentifier serviceId);
	
	/**
	 * This method is used by a third-party client service to get the serviceId of its parent/server
	 * 
	 * @param serviceId
	 * @return the serviceId of the parent
	 */
	public ServiceResourceIdentifier getServerServiceIdentifier(ServiceResourceIdentifier serviceId);

	/**
	 *  This method compares to ServiceResourceIdentifiers to determine if they are equal. It is, effectively, an "equals" method
	 *  as the ServiceResourceIdentifier does not have one, since it is a bean.
	 *  
	 * @param serviceId
	 * @param otherServiceId
	 * @return true if they are equal, false otherwise.
	 */
	public boolean compare(ServiceResourceIdentifier serviceId, ServiceResourceIdentifier otherServiceId);

	/**
	 * This method allows a service to retrieve its category, for example "media" or "calendar"
	 * 
	 * @param serviceId
	 * @return the service category
	 */
	public String getMyCategory(ServiceResourceIdentifier serviceId);

	/**
	 * @param serviceId
	 * @param node
	 * @return
	 */
	boolean shareService(ServiceResourceIdentifier serviceId, IIdentity node);
	

}