/*****************************************************************
JADE - Java Agent DEvelopment Framework is a framework to develop
multi-agent systems in compliance with the FIPA specifications.
Copyright (C) 2000 CSELT S.p.A.
GNU Lesser General Public License
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation,
version 2.1 of the License.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*****************************************************************/
package jade.core;
//#APIDOC_EXCLUDE_FILE
import java.util.Vector;
import jade.security.JADESecurityException;
/**
The <code>ServiceManager</code> interface serves as an access point
for kernel-level service management. From a service manager object
one can add and remove a service, or perform service management
activities such as service suspension, resumption or parameter
tuning.
@author Giovanni Rimassa - FRAMeTech s.r.l.
@see jade.core.Service
*/
public interface ServiceManager {
/**
Retrieves the platform name from the platform <i>Service Manager</i>.
@return The name of the platform, that can be used to compose
the GUID of the resident agents.
@throws IMTPException If an underlying network error forbids to
fetch the name from the remote end.
*/
String getPlatformName() throws IMTPException;
/**
Adds an address to the address list of this <i>Service Manager</i>.
@param addr The address to add, as a stringified URL.
@throws IMTPException If an underlying network error occurs.
*/
void addAddress(String addr) throws IMTPException;
/**
Removes an address to the address list of this <i>Service Manager</i>.
@param addr The address to remove, as a stringified URL.
@throws IMTPException If an underlying network error occurs.
*/
void removeAddress(String addr) throws IMTPException;
/**
Access the address exported by this copy of the <i>Service
Manager</i>.
@return The locally exported address.
@throws IMTPException If an underlying network error occurs.
*/
String getLocalAddress() throws IMTPException;
/**
Adds a new node to the distributed platform. The node
abstraction can correspond to an agent container, but also to a
different kind of networked component (command proxy server,
persistent repository, etc.) of the JADE platform.
@param desc The description of the new node to add, containing
the node identifier and other node properties.
@param services An array of <code>ServiceDescriptor</code>
objects, describing the various kernel-level services that are
to be activated on the newly created node.
@throws IMTPException If an underlying network error forbids to
tell whether the requested operation was possible. In that
case, the operation is not executed.
@throws ServiceException If the requested operation couldn't be
executed (or an execution attempt failed) due to some condition
on the remote end.
*/
void addNode(NodeDescriptor desc, ServiceDescriptor[] services) throws IMTPException, ServiceException, JADESecurityException;
/**
Removes a node from the distributed platform. The node
abstraction can correspond to an agent container, but also to a
different kind of networked component (command proxy server,
persistent repository, etc.) of the JADE platform.
@param desc The description of the node to remove. At the very
least, the description must contain a node identifier used as a
key in node findng operations.
@throws IMTPException If an underlying network error forbids to
tell whether the requested operation was possible. In that
case, the operation is not executed.
@throws ServiceException If the requested operation couldn't be
executed (or an execution attempt failed) due to some condition
on the remote end.
*/
void removeNode(NodeDescriptor desc) throws IMTPException, ServiceException;
/**
Activates a new service on the local agent container. Depending
on whether the service is already active on other containers,
the result can be the actual federation of this container and
other containers service slices.
@param desc The <code>ServiceDescriptor</code> object
specifying the <code>Service</code> object implementing the
service, along with the name and properties of the service.
@throws IMTPException If an underlying network error forbids to
tell whether the requested operation was possible. In that
case, the operation is not executed.
@throws ServiceException If the requested operation couldn't be
executed (or an execution attempt failed) due to some condition
on the remote end.
@see jade.core.ServiceFinder
*/
void activateService(ServiceDescriptor desc) throws IMTPException, ServiceException;
/**
Deactivates a service on the local container. Depending on
whether the service is enabled also on other containers, this
method can cause the complete service deactivation on the
platform or just the detchmnent of the service slice
corresponding to this container.
@param name The name of the service to be deactivated.
@throws IMTPException If an underlying network error forbids to
tell whether the requested operation was possible. In that
case, the operation is not executed.
@throws ServiceException If the requested operation couldn't be
executed (or an execution attempt failed) due to some condition
on the remote end.
@see jade.core.ServiceFinder
*/
void deactivateService(String name) throws IMTPException, ServiceException;
/**
* Retrieve the list of locally installed services as a Vector of ServiceDescriptor objects
* @return the list of locally installed services as a Vector of ServiceDescriptor objects
*/
Vector getLocalServices();
}