/*************************************************************************
*
* ADOBE CONFIDENTIAL __________________
*
* Copyright 2002 - 2007 Adobe Systems Incorporated All Rights Reserved.
*
* NOTICE: All information contained herein is, and remains the property of Adobe Systems Incorporated and its suppliers, if any. The intellectual and technical concepts contained herein are
* proprietary to Adobe Systems Incorporated and its suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law. Dissemination of
* this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from Adobe Systems Incorporated.
**************************************************************************/
package flex.messaging.services;
import java.util.List;
import java.util.Map;
import flex.management.Manageable;
import flex.messaging.Destination;
import flex.messaging.FlexComponent;
import flex.messaging.MessageBroker;
import flex.messaging.config.ConfigMap;
import flex.messaging.endpoints.Endpoint;
import flex.messaging.messages.CommandMessage;
import flex.messaging.messages.Message;
/**
* The MessageBroker has endpoints on one end and services on the other. The Service interface defines the contract between the MessageBroker and all Service implementations.
*
* @author sneville
*/
public interface Service extends Manageable, FlexComponent
{
/**
* Returns the adapters registered with the <code>Service</code>.
*
* @return The Map of adapter id and classes.
*/
Map getRegisteredAdapters();
/**
* Registers the adapter with the <code>Service</code>.
*
* @param id
* The id of the adapter.
* @param className
* The class of the adapter.
* @return The previous adapter class that the id was associated with.
*/
String registerAdapter(String id, String className);
/**
* Unregistered the adapter with the <code>Service</code> and set the default adapter to <code>null</code> if needed.
*
* @param id
* The id of the adapter.
* @return The adapter class that the id was associated with.
*/
String unregisterAdapter(String id);
/**
* Returns the id of the default adapter of the <code>Service</code>.
*
* @return The id of the default adapter of the <code>Service</code>.
*/
String getDefaultAdapter();
/**
* Sets the id of the default adapter of the <code>Service</code>.
*
* @param id
* The id of the default adapter of the <code>Service</code>.
*/
void setDefaultAdapter(String id);
/**
* Returns the list of channel ids of the <code>Service</code>.
*
* @return The list of channel ids of the <code>Service</code>.
*/
List getDefaultChannels();
/**
* Adds the channel to the list of channels of the <code>Service</code>. <code>MessageBroker</code> has to know the channel. Otherwise, the channel should not added to the list.
*
* @param id
* The id of the channel.
*/
void addDefaultChannel(String id);
/**
* Sets the channel list of the <code>Service</code>. <code>MessageBroker</code> has to know the channels, otherwise they should not be added to the list.
*
* @param ids
* List of channel ids.
*/
void setDefaultChannels(List ids);
/**
* Removes the channel from the list of channels for the <code>AbstractService</code>.
*
* @param id
* The id of the channel.
* @return <code>true</code> if the list contained the channel id.
*/
boolean removeDefaultChannel(String id);
/**
* Retrieves the destination in this service for which the given message is intended.
*
* @param message
* The message.
* @return The <code>Destination</code> in this service for which the given message is intended.
*/
Destination getDestination(Message message);
/**
* Returns the <code>Destination</code> with the specified id or null if no <code>Destination</code> with id exists.
*
* @param id
* The id of the <code>Destination</code>.
* @return The <code>Destination</code> with the specified id or null.
*/
Destination getDestination(String id);
/**
* Returns the Map of <code>Destination</code> ids and instances.
*
* @return The Map of <code>Destination</code> ids and instances.
*/
Map getDestinations();
/**
* Creates a <code>Destination</code> instance, sets its id, sets it manageable if the <code>Service</code> that created it is manageable, and sets its <code>Service</code> to the
* <code>Service</code> that created it.
*
* @param id
* The id of the <code>Destination</code>.
* @return The <code>Destination</code> instanced created.
*/
Destination createDestination(String id);
/**
* Adds the <code>Destination</code> to the <code>Service</code>.
*
* @param destination
* The <code>Destination</code> to be added.
*/
void addDestination(Destination destination);
/**
* Remove the <code>Destination</code> from the <code>Service</code>.
*
* @param id
* The id of the <code>Destination</code>.
* @return Previous <code>Destination</code> associated with the id.
*/
Destination removeDestination(String id);
/**
* Returns the id for the service.
*
* @return The id for the service.
*/
String getId();
/**
* Sets the id for the service.
*
* @param id
* The id for the service.
*/
void setId(String id);
/**
* All services must be managed by a single MessageBroker, and must be capable of returning a reference to that broker. This broker is used when a service wishes to push a message to one or more
* endpoints managed by the broker.
*
* @return broker The MessageBroker instance which manages this service
*/
MessageBroker getMessageBroker();
/**
* Sets the <code>MessageBroker</code> of the <code>Service</code>.
*
* @param broker
* The <code>MessageBroker</code> of the <code>Service</code>.
*/
void setMessageBroker(MessageBroker broker);
/**
* Describes the service for the client.
*
* @param endpoint
* Endpoint used to filter the service destinations.
* @return ConfigMap of service properties.
*/
ConfigMap describeService(Endpoint endpoint);
/**
* Handles a message routed to the service by the MessageBroker.
*
* @param message
* The message sent by the MessageBroker.
* @return The result of the service.
*/
Object serviceMessage(Message message);
/**
* Handles a command routed to the service by the MessageBroker. Usually these are commands sent by one of the endpoints.
*
* @param message
* The message sent by the MessageBroker.
* @return The result of the service.
*/
Object serviceCommand(CommandMessage message);
}