001 /*
002 * JBoss, Home of Professional Open Source
003 * Copyright 2011 Red Hat Inc. and/or its affiliates and other contributors
004 * as indicated by the @author tags. All rights reserved.
005 * See the copyright.txt in the distribution for a
006 * full listing of individual contributors.
007 *
008 * This copyrighted material is made available to anyone wishing to use,
009 * modify, copy, or redistribute it subject to the terms and conditions
010 * of the GNU Lesser General Public License, v. 2.1.
011 * This program is distributed in the hope that it will be useful, but WITHOUT A
012 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
013 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
014 * You should have received a copy of the GNU Lesser General Public License,
015 * v.2.1 along with this distribution; if not, write to the Free Software
016 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
017 * MA 02110-1301, USA.
018 */
019 package org.switchyard;
020
021 import org.switchyard.metadata.ExchangeContract;
022 import org.switchyard.metadata.ServiceOperation;
023
024 /**
025 * An Exchange represents an instance of a service invocation with a specific
026 * message exchange pattern (e.g. InOnly, InOut). Exchange provides a conduit
027 * for the messages that flow into and out of a service as part of a service
028 * invocation. Unlike messages, an exchange cannot be copied and reused across
029 * service invocations. State associated with an invocation (i.e. context) is
030 * maintained at the exchange level.
031 */
032 public interface Exchange {
033
034 /**
035 * Context property name used for Message ID.
036 */
037 String MESSAGE_ID = "org.switchyard.messageId";
038
039 /**
040 * Context property name used for Relates To.
041 */
042 String RELATES_TO = "org.switchyard.relatesTo";
043
044 /**
045 * Context property name used for Message Content Type.
046 */
047 String CONTENT_TYPE = "org.switchyard.contentType";
048
049 /**
050 * Context property name used for Operation Name.
051 */
052 String OPERATION_NAME = "org.switchyard.operationName";
053
054 /**
055 * Context property name used for Fault Type.
056 */
057 String FAULT_TYPE = "org.switchyard.faultType";
058
059 /**
060 * Context property name used for Service Name.
061 */
062 String SERVICE_NAME = "org.switchyard.serviceName";
063
064 /**
065 * Retrieves the exchange context.
066 * @return the exchange context
067 */
068 Context getContext();
069
070 /**
071 * Get the service reference representing the consumer.
072 * @return The consumer service reference instance.
073 */
074 ServiceReference getConsumer();
075
076 /**
077 * Get the service representing the provider. This method will return
078 * null before an exchange is sent for the first time.
079 * @return the provider's service
080 */
081 Service getProvider();
082
083 /**
084 * The contract between consumer and provider for this exchange.
085 * @return exchange contract
086 */
087 ExchangeContract getContract();
088
089 /**
090 * Set service consumer info for this exchange.
091 * @param consumer the service reference used by the exchange
092 * @param operation the operation being invoked
093 * @return this Exchange instance
094 */
095 Exchange consumer(ServiceReference consumer, ServiceOperation operation);
096
097 /**
098 * Set service provider info for this exchange.
099 * @param provider the service provider used by the exchange
100 * @param operation the operation being invoked
101 * @return this Exchange instance
102 */
103 Exchange provider(Service provider, ServiceOperation operation);
104
105 /**
106 * Returns the current message for the exchange. On new exchanges, this
107 * method will always return null. The current message reference is updated
108 * with each call to send().
109 * @return the current message for the exchange
110 */
111 Message getMessage();
112
113 /**
114 * Create a message to be used with this exchange.
115 * @return new message
116 */
117 Message createMessage();
118
119 /**
120 * Sends the specified message as part of this message exchange.
121 * <p/>
122 * Implementations must throw an {@link IllegalStateException} if this method is
123 * called when the Exchange {@link #getState() state} is in {@link ExchangeState#FAULT}.
124 * @param message message to send
125 */
126 void send(Message message);
127
128 /**
129 * Sends the specified message as part of this message exchange.
130 * <p/>
131 * Also sets the Exchange {@link #getState() state} to {@link ExchangeState#FAULT}.
132 * @param message message to send
133 */
134 void sendFault(Message message);
135
136 /**
137 * Get the exchange state.
138 * @return The exchange State.
139 */
140 ExchangeState getState();
141
142 /**
143 * Get the exchange phase.
144 * @return the exchange phase
145 */
146 ExchangePhase getPhase();
147
148 }