flex.messaging.services.Service Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of flex-messaging-core Show documentation
There is a newer version: 4.8.0
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package flex.messaging.services;

import java.util.List;
import java.util.Map;

import flex.management.Manageable;
import flex.messaging.FlexComponent;
import flex.messaging.MessageBroker;
import flex.messaging.Destination;
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 Service.
     *
     * @return The Map of adapter id and classes.
     */
    Map getRegisteredAdapters();

    /**
     * Registers the adapter with the Service.
     *
     * @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 Service and
     * set the default adapter to null 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 Service.
     *
     * @return The id of the default adapter of the Service.
     */
    String getDefaultAdapter();

    /**
     * Sets the id of the default adapter of the Service.
     *
     * @param id The id of the default adapter of the Service.
     */
    void setDefaultAdapter(String id);

    /**
     * Returns the list of channel ids of the Service.
     *
     * @return The list of channel ids of the Service.
     */
    List getDefaultChannels();

    /**
     * Adds the channel to the list of channels of the Service.
     * MessageBroker 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 Service.
     * MessageBroker 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 AbstractService.
     *
     * @param id The id of the channel.
     * @return true 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 Destination in this service for which the given message is intended.
     */
    Destination getDestination(Message message);

    /**
     * Returns the Destination with the specified id or null if no
     * Destination with id exists.
     *
     * @param id The id of the Destination.
     * @return The Destination with the specified id or null.
     */
    Destination getDestination(String id);

    /**
     * Returns the Map of Destination ids and instances.
     *
     * @return The Map of Destination ids and instances.
     */
    Map getDestinations();

    /**
     * Creates a Destination instance, sets its id, sets it manageable
     * if the Service that created it is manageable,
     * and sets its Service to the Service that
     * created it.
     *
     * @param id The id of the Destination.
     * @return The Destination instanced created.
     */
    Destination createDestination(String id);

    /**
     * Adds the Destination to the Service.
     *
     * @param destination The Destination to be added.
     */
    void addDestination(Destination destination);

    /**
     * Remove the Destination from the Service.
     *
     * @param id The id of the Destination.
     * @return Previous Destination 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 MessageBroker of the Service.
     *
     * @param broker The MessageBroker of the Service.
     */
    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);
}