/*
 * 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 javax.jbi.messaging;

import java.net.URI;

import javax.jbi.servicedesc.ServiceEndpoint;

import javax.xml.namespace.QName;

/**
 * MessageExchange represents a container for normalized messages which
 * are described by an exchange pattern. The exchange pattern defines the
 * names, sequence, and cardinality of messages in an exchange.
 *
 * @author JSR208 Expert Group
 */
public interface MessageExchange {

    /**
     * JTA transaction context property name.
     */
    String JTA_TRANSACTION_PROPERTY_NAME = "javax.jbi.transaction.jta";

    /**
     * Returns the URI of the pattern for this exchange.
     *
     * @return pattern URI for this exchange
     */
    URI getPattern();

    /**
     * Returns the unique identifier assigned by the NMS for this exchange.
     *
     * @return unique id for this exchange
     */
    String getExchangeId();

    /**
     * Returns the processing status of the exchange.
     *
     * @return status of the exchange
     */
    ExchangeStatus getStatus();

    /**
     * Sets the processing status of the exchange.
     *
     * @param status exchange status
     * @throws MessagingException failed to set status, possibly due to
     *                            an invalid state transition.
     */
    void setStatus(ExchangeStatus status) throws MessagingException;

    /**
     * Used to specify the source of a failure status. Invoking this method
     * automatically adjusts the status of the ME to {@link ExchangeStatus#ERROR}.
     *
     * @param error error cause
     */
    void setError(Exception error);

    /**
     * Retrieves the Exception describing the exchanges error status.
     *
     * @return exception associated with this exchange
     */
    Exception getError();

    /**
     * Retrieves the fault message for this exchange, if one exists. A fault/message
     * reference is unnecessary, since an exchange can carry at most one fault, and
     * it is always the final message in an exchange.
     *
     * @return fault associated with the exchange, or null if not present
     */
    Fault getFault();

    /**
     * Specifies the fault message for this exchange, if one exists. A fault/message
     * reference is unnecessary, since an exchange can carry at most one fault, and
     * it is always the final message in an exchange.
     *
     * @param fault fault
     * @throws MessagingException operation not permitted in the current exchange state
     */
    void setFault(Fault fault) throws MessagingException;

    /**
     * Creates a normalized message based on the specified message reference. The pattern
     * governing this exchange must contain a definition for the reference name supplied.
     *
     * @return a new normalized message
     * @throws MessagingException failed to create message
     */
    NormalizedMessage createMessage() throws MessagingException;

    /**
     * Generic factory method for Fault objects.
     *
     * @return a new fault
     * @throws MessagingException failed to create fault
     */
    Fault createFault() throws MessagingException;

    /**
     * Retrieves a normalized message based on the specified message reference.
     *
     * @param name message reference
     * @return message with the specified reference name
     */
    NormalizedMessage getMessage(String name);

    /**
     * Sets a normalized message with the specified message reference. The pattern
     * governing this exchange must contain a definition for the reference name
     * supplied.
     *
     * @param msg normalized message
     * @param name message reference
     * @throws MessagingException operation not permitted in the current exchange state
     */
    void setMessage(NormalizedMessage msg, String name) throws MessagingException;

    /**
     * Retrieves the specified property from the exchange.
     *
     * @param name property name
     * @return property value
     */
    Object getProperty(String name);

    /**
     * Specifies a property for the exchange.
     *
     * @param name property name
     * @param obj property value
     */
    void setProperty(String name, Object obj);

    /**
     * Specifies the endpoint used by this exchange.
     *
     * @param endpoint endpoint address
     */
    void setEndpoint(ServiceEndpoint endpoint);

    /**
     * Specifies the service used by this exchange.
     *
     * @param service service address
     */
    void setService(QName service);

    /**
     * Specifies the interface name used by this exchange.
     *
     * @param interfaceName interface name
     */
    void setInterfaceName(QName interfaceName);

    /**
     * Specifies the operation used by this exchange.
     *
     * @param name operation name
     */
    void setOperation(QName name);

    /**
     * Retrieves the endpoint used by this exchange.
     *
     * @return endpoint address for this message exchange
     */
    ServiceEndpoint getEndpoint();

    /**
     * Retrieves the interface name used by this exchange.
     *
     * @return interface used for this message exchange
     */
    QName getInterfaceName();

    /**
     * Retrieves the service used by this exchange.
     * 
     * @return service address for this message exchange
     */
    QName getService();

    /**
     * Retrieves the operation used by this exchange.
     * 
     * @return operation name for this message exchange
     */
    QName getOperation();

    /**
     * Queries the existence of a transaction context.
     * 
     * @return boolean transactional state of the exchange
     */
    boolean isTransacted();

    /**
     * Queries the role that the caller plays in the exchange.
     *
     * @return Role expected of caller.
     */
    Role getRole();

    /**
     * Returns the name of all properties for this exchange.
     * 
     * @return a set of all the property names, as Strings.
     */
    java.util.Set getPropertyNames();

    /**
     * Typesafe enum containing the roles a component can play in a service.
     * 
     */
    public static final class Role {

        /**
         * Service provider.
         */
        public static final Role PROVIDER = new Role();

        /**
         * Service Consumer.
         */
        public static final Role CONSUMER = new Role();

        /**
         * Prevent direct instantiation.
         */
        private Role() {
        }
    }
}