/*
* @@COPYRIGHT@@
*/
package com.cosylab.acs.maci;
/**
* Every client of a Component service that is not itself a Component must implement an interface called Client.
* The interface allows the client to act as a secure party in the communication with the components,
* to receive general-purpose string messages from the MACI components and to be notified when
* any change happens to the components that the client utilizes. Each client logs in to the MACI system
* before any other requests are made, and in turn it obtains an handle,
* which it must use in every subsequent request to the MACI.
*
* @author Matej Sekoranja (matej.sekoranja@cosylab.com)
* @version @@VERSION@@
*/
public interface Client
{
/**
* Authentication method.
* Method authenticate is the challenge issued to the client after it tries to login.
* The login will be successful if the client's authenticate() produces the expected result.
* Only in this case will the Manager's login method return a valid handle,
* which the client will later use as the id parameter with all calls to the Manager.
*
* @param question The question posed by the Manager.
* @return authentication structure (including answer to the question).
**/
public AuthenticationData authenticate(long executionId, String question) throws RemoteException;
/**
* Notify client about the change (availability) of the components currently in use by this client.
* For administrative clients, notification is issued for the change of availability of any component in the domain.
*
* @param cobs A sequence of ComponentInfo structures identifying the affected components.
* Regular clients receive the name, the type, the handle and the reference of the newly activated component.
* Administrative clients also receive the handle of the container where the component was activated.
*/
public void components_available(ComponentInfo[] components) throws RemoteException;
/**
* Notify client that some of the components currently in use by client have become unavailable.
*
* @param cobs CURLs of the unavailable components.
*/
public void components_unavailable(String[] components) throws RemoteException;
/**
* Disconnect notification.
* The disconnect method is called by the Manager to notify the client that
* it will be unavailable and that the client should log off.
*/
public void disconnect() throws RemoteException;
/**
* The Manager and administrators use this method for sending textual messages to the client.
*
* @param type Type of the message, instance of <code>MessageType</code>.
* @param message Contents of the message. The contents are human readable.
*/
public void message(MessageType type, String message) throws RemoteException;
/**
* The Manager and administrators use this method for sending tagged textual messages to the client.
*
* @param type Type of the message, instance of <code>MessageType</code>.
* @param id Tag of the message, integer
* @param message Contents of the message. The contents are human readable.
*/
public void taggedmessage(MessageType type, short id, String message) throws RemoteException;
/**
* Client name.
* @return name
*/
public String name() throws RemoteException;
/**
* Manager pings its clients (both GUI clients, as well as Containers) repeatedly to verify that they still exist.
* The return value can be either "true", indicating that everything is OK with the client,
* or "false", indicating that client is malfunctioning.
*
* If <code>RemoteTransientException</code> exception is thrown, the Manager should retry the ping several times,
* and only then shall the client be assumed to be malfunctioning.
* If another exception is thrown, the client may be immediately assumed to be malfunctioning.
* Once the client is found to be malfunctioning, the Manager makes an implicit logout of the client.
*/
public boolean ping() throws RemoteException;
/**
* Get location string (host@port).
*/
public String getRemoteLocation() throws RemoteException;
/**
* Release remote resources of this object.
* @throws RemoteException
*/
public void release();
}