001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package javax.jbi.messaging; 018 019 import java.net.URI; 020 021 import javax.jbi.servicedesc.ServiceEndpoint; 022 023 import javax.xml.namespace.QName; 024 025 /** 026 * MessageExchange represents a container for normalized messages which 027 * are described by an exchange pattern. The exchange pattern defines the 028 * names, sequence, and cardinality of messages in an exchange. 029 * 030 * @author JSR208 Expert Group 031 */ 032 public interface MessageExchange { 033 034 /** 035 * JTA transaction context property name. 036 */ 037 String JTA_TRANSACTION_PROPERTY_NAME = "javax.jbi.transaction.jta"; 038 039 /** 040 * Returns the URI of the pattern for this exchange. 041 * 042 * @return pattern URI for this exchange 043 */ 044 URI getPattern(); 045 046 /** 047 * Returns the unique identifier assigned by the NMS for this exchange. 048 * 049 * @return unique id for this exchange 050 */ 051 String getExchangeId(); 052 053 /** 054 * Returns the processing status of the exchange. 055 * 056 * @return status of the exchange 057 */ 058 ExchangeStatus getStatus(); 059 060 /** 061 * Sets the processing status of the exchange. 062 * 063 * @param status exchange status 064 * @throws MessagingException failed to set status, possibly due to 065 * an invalid state transition. 066 */ 067 void setStatus(ExchangeStatus status) throws MessagingException; 068 069 /** 070 * Used to specify the source of a failure status. Invoking this method 071 * automatically adjusts the status of the ME to {@link ExchangeStatus#ERROR}. 072 * 073 * @param error error cause 074 */ 075 void setError(Exception error); 076 077 /** 078 * Retrieves the Exception describing the exchanges error status. 079 * 080 * @return exception associated with this exchange 081 */ 082 Exception getError(); 083 084 /** 085 * Retrieves the fault message for this exchange, if one exists. A fault/message 086 * reference is unnecessary, since an exchange can carry at most one fault, and 087 * it is always the final message in an exchange. 088 * 089 * @return fault associated with the exchange, or null if not present 090 */ 091 Fault getFault(); 092 093 /** 094 * Specifies the fault message for this exchange, if one exists. A fault/message 095 * reference is unnecessary, since an exchange can carry at most one fault, and 096 * it is always the final message in an exchange. 097 * 098 * @param fault fault 099 * @throws MessagingException operation not permitted in the current exchange state 100 */ 101 void setFault(Fault fault) throws MessagingException; 102 103 /** 104 * Creates a normalized message based on the specified message reference. The pattern 105 * governing this exchange must contain a definition for the reference name supplied. 106 * 107 * @return a new normalized message 108 * @throws MessagingException failed to create message 109 */ 110 NormalizedMessage createMessage() throws MessagingException; 111 112 /** 113 * Generic factory method for Fault objects. 114 * 115 * @return a new fault 116 * @throws MessagingException failed to create fault 117 */ 118 Fault createFault() throws MessagingException; 119 120 /** 121 * Retrieves a normalized message based on the specified message reference. 122 * 123 * @param name message reference 124 * @return message with the specified reference name 125 */ 126 NormalizedMessage getMessage(String name); 127 128 /** 129 * Sets a normalized message with the specified message reference. The pattern 130 * governing this exchange must contain a definition for the reference name 131 * supplied. 132 * 133 * @param msg normalized message 134 * @param name message reference 135 * @throws MessagingException operation not permitted in the current exchange state 136 */ 137 void setMessage(NormalizedMessage msg, String name) throws MessagingException; 138 139 /** 140 * Retrieves the specified property from the exchange. 141 * 142 * @param name property name 143 * @return property value 144 */ 145 Object getProperty(String name); 146 147 /** 148 * Specifies a property for the exchange. 149 * 150 * @param name property name 151 * @param obj property value 152 */ 153 void setProperty(String name, Object obj); 154 155 /** 156 * Specifies the endpoint used by this exchange. 157 * 158 * @param endpoint endpoint address 159 */ 160 void setEndpoint(ServiceEndpoint endpoint); 161 162 /** 163 * Specifies the service used by this exchange. 164 * 165 * @param service service address 166 */ 167 void setService(QName service); 168 169 /** 170 * Specifies the interface name used by this exchange. 171 * 172 * @param interfaceName interface name 173 */ 174 void setInterfaceName(QName interfaceName); 175 176 /** 177 * Specifies the operation used by this exchange. 178 * 179 * @param name operation name 180 */ 181 void setOperation(QName name); 182 183 /** 184 * Retrieves the endpoint used by this exchange. 185 * 186 * @return endpoint address for this message exchange 187 */ 188 ServiceEndpoint getEndpoint(); 189 190 /** 191 * Retrieves the interface name used by this exchange. 192 * 193 * @return interface used for this message exchange 194 */ 195 QName getInterfaceName(); 196 197 /** 198 * Retrieves the service used by this exchange. 199 * 200 * @return service address for this message exchange 201 */ 202 QName getService(); 203 204 /** 205 * Retrieves the operation used by this exchange. 206 * 207 * @return operation name for this message exchange 208 */ 209 QName getOperation(); 210 211 /** 212 * Queries the existence of a transaction context. 213 * 214 * @return boolean transactional state of the exchange 215 */ 216 boolean isTransacted(); 217 218 /** 219 * Queries the role that the caller plays in the exchange. 220 * 221 * @return Role expected of caller. 222 */ 223 Role getRole(); 224 225 /** 226 * Returns the name of all properties for this exchange. 227 * 228 * @return a set of all the property names, as Strings. 229 */ 230 java.util.Set getPropertyNames(); 231 232 /** 233 * Typesafe enum containing the roles a component can play in a service. 234 * 235 */ 236 public static final class Role { 237 238 /** 239 * Service provider. 240 */ 241 public static final Role PROVIDER = new Role(); 242 243 /** 244 * Service Consumer. 245 */ 246 public static final Role CONSUMER = new Role(); 247 248 /** 249 * Prevent direct instantiation. 250 */ 251 private Role() { 252 } 253 } 254 }