IRemoteService.java

/****************************************************************************
 * Copyright (c) 2004, 2009 Composent, Inc. and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Composent, Inc. - initial API and implementation
 *****************************************************************************/

package org.eclipse.ecf.remoteservice;

import org.eclipse.ecf.core.util.ECFException;
import org.eclipse.equinox.concurrent.future.IFuture;

/**
 * Interface providing runtime access to a remote service. An instance
 * implementing this interface will be returned from the
 * IRemoteServiceContainerAdapter.getRemoteService(IRemoteServiceReference) and
 * may then be used to communicate with a remote service. The methods on this
 * interface support accessing the remote service in several ways:<br>
 * <ul>
 * <li>callSync -- A synchronous invocation that will block the calling thread
 * until complete (or timeout) and return the result from the remote or throw
 * exception if remote invocation fails or throws exception</li>
 * <li>callAsync/1 -- An asynchronous invocation that will not block the caller
 * thread but rather return a non-<code>null</code> {@link IFuture} instance
 * that can be polled for results.  See {@link IFuture#get()},
 * {@link IFuture#get(long)}, and {@link IFuture#isDone()}.
 * timeout, exception, or successful completion)</li>
 * <li>callAsync/2 -- An asynchronous invocation that will not block the caller
 * thread but rather notify the given listener asynchronously when complete (via
 * timeout, exception, or successful completion)</li>
 * <li>fireAsync -- An asynchronous invocation that will simply execute the
 * remote method asynchronously, but will not provide any response or remote
 * method failure information</li>
 * <li>getProxy -- Access to a local proxy for the remote service that will
 * expose the appropriate interface to the caller, and synchronously call the
 * remote methods when invoked. 
 * </ul>
 * 
 */
public interface IRemoteService {
	/**
	 * Call remote method specified by call parameter synchronously.
	 * 
	 * @param call
	 *            the remote call to make
	 * @return Object the result of the call. Will be <code>null</code> if
	 *         remote provides <code>null</code> as result.
	 * @throws ECFException
	 *             thrown if disconnect occurs, caller not currently connected,
	 *             or remote throws Exception
	 * @since 3.0
	 */
	public Object callSync(IRemoteCall call) throws ECFException;

	/**
	 * Call remote method specified by call parameter asynchronously, and notify
	 * specified listener when call starts and completes.
	 * 
	 * @param call
	 *            the remote call to make. Must not be <code>null</code> .
	 * @param listener
	 *            the listener to notify when call starts and is completed. The
	 *            listener will be notified via the two event types
	 *            IRemoteCallStartEvent and IRemoteCallCompleteEvent. Must not
	 *            be <code>null</code> .
	 * 
	 * @see org.eclipse.ecf.remoteservice.events.IRemoteCallStartEvent
	 * @see org.eclipse.ecf.remoteservice.events.IRemoteCallCompleteEvent
	 * @since 3.0
	 */
	public void callAsync(IRemoteCall call, IRemoteCallListener listener);

	/**
	 * Call remote method specified by call parameter asynchronously, and immediately
	 * return {@link IFuture} instance.  Returned IFuture will not be <code>null</code>,
	 * and allows the caller to retrieve the actual resulting value from the remote call
	 * (or exception).
	 * 
	 * @param call the remote call to make. Must not be <code>null</code> .
	 * @return IFuture the asynchronous result to allow the caller to poll
	 * for whether the result {@link IFuture#isDone()}, and then to {@link IFuture#get()}
	 * the actual result.
	 * @since 3.0
	 */
	public IFuture callAsync(IRemoteCall call);

	/**
	 * Fire remote method specified by call parameter. The remote method will be
	 * invoked as a result of asynchronous message send, but no
	 * failure/exception information will be returned, and no result will be
	 * returned
	 * 
	 * @param call
	 *            the remote call to make. Must not be <code>null</code> .
	 * @throws ECFException
	 *             if caller not currently connected
	 * @since 3.0
	 */
	public void fireAsync(IRemoteCall call) throws ECFException;

	/**
	 * Get local proxy for remote interface. The local proxy may then be used to
	 * make remote method calls transparently by invoking the local proxy method
	 * 
	 * @return Object that implements the interface specified in the
	 *         IRemoteServiceReference instance used to retrieve the
	 *         IRemoteService object. The result may then be cast to the
	 *         appropriate type. Will not be <code>null</code>.
	 * @throws ECFException
	 *             If some problem in creating the proxy.  The underlying problem is 
	 *             conveyed in the nested exception.
	 */
	public Object getProxy() throws ECFException;

	/**
	 * Get local proxy for remote interface. The local proxy may then be used to
	 * make remote method calls transparently by invoking the local proxy method
	 * 
	 * @param cl ClassLoader to use to create the proxy class.  
	 *         Must not be <code>null</code>. 
	 * @param interfaceClasses array of Class that has the loaded interface classes.  
	 *         Must not be <code>null</code> and should have dimension of one or more.
	 * @return Object that implements the given interfaceClasses.  The result may then 
	 *         be cast to the one of the types given in interfaceClasses. Will not be
	 *         <code>null</code>
	 * @throws ECFException
	 *             If some problem in creating the proxy.  The underlying problem is 
	 *             conveyed in the nested exception.
	 * @since 6.0
	 */
	public Object getProxy(ClassLoader cl, Class[] interfaceClasses) throws ECFException;

}