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: * $Header:$
018: */
019: package org.apache.beehive.controls.system.jms;
020:
021: import java.lang.annotation.Retention;
022: import java.lang.annotation.RetentionPolicy;
023: import java.lang.annotation.ElementType;
024: import java.lang.annotation.Target;
025: import java.util.Map;
026: import javax.jms.Session;
027:
028: import org.apache.beehive.controls.api.ControlException;
029: import org.apache.beehive.controls.api.bean.AnnotationMemberTypes;
030: import org.apache.beehive.controls.api.bean.ControlInterface;
031: import org.apache.beehive.controls.api.bean.AnnotationConstraints;
032: import org.apache.beehive.controls.api.packaging.FeatureInfo;
033: import org.apache.beehive.controls.api.properties.PropertySet;
034:
035: /**
036: * The control interface for the jms control.
037: */
038: @ControlInterface(defaultBinding="org.apache.beehive.controls.system.jms.impl.JMSControlImpl")
039: public interface JMSControl {
040: /**
041: * The destination type.
042: */
043: enum DestinationType {
044: /** The destination is set from the object obtained from JNDI. */
045: Auto,
046: /** The destination must be a javax.jms.QueueSender. */
047: Queue,
048: /** The destination must be a javax.jms.TopicPublisher. */
049: Topic
050: };
051:
052: /**
053: * The header type. Corresponds to the JMS* bean properties on a JMS message.
054: */
055: enum HeaderType {
056: /** @see javax.jms.Message#getJMSCorrelationID */
057: JMSCorrelationID,
058: /** @see javax.jms.Message#getJMSDeliveryMode */
059: JMSDeliveryMode,
060: /** @see javax.jms.Message#getJMSPriority */
061: JMSPriority,
062: /** @see javax.jms.Message#getJMSExpiration */
063: JMSExpiration,
064: /** @see javax.jms.Message#getJMSMessageID */
065: JMSMessageID,
066: /** @see javax.jms.Message#getJMSType */
067: JMSType,
068: /** @see javax.jms.Message#getJMSRedelivered */
069: JMSRedelivered,
070: /** @see javax.jms.Message#getJMSTimestamp */
071: JMSTimestamp
072: };
073:
074: /**
075: * The message type.
076: */
077: enum MessageType {
078: /** Message is determined from the body instance class. If the method is not annotated with Body, then the message type is Map. */
079: Auto,
080: /** Message is a {@link javax.jms.TextMessage} */
081: Text,
082: /** Message is a {@link javax.jms.BytesMessage} */
083: Bytes,
084: /** Message is a {@link javax.jms.ObjectMessage} */
085: Object,
086: /** Message is a {@link javax.jms.MapMessage} */
087: Map,
088: /** Message is a {@link javax.jms.Message} as given by the Body parameter */
089: JMSMessage
090: };
091:
092: /**
093: * The delivery mode.
094: */
095: enum DeliveryMode {
096: /**
097: * @see javax.jms.DeliveryMode#NON_PERSISTENT
098: */
099: NonPersistent,
100: /**
101: * @see javax.jms.DeliveryMode#PERSISTENT
102: */
103: Persistent,
104: /** The default for the provider */
105: Auto
106: };
107:
108: /**
109: * The acknowledge mode.
110: */
111: enum AcknowledgeMode {
112: /**
113: * @see javax.jms.Session#AUTO_ACKNOWLEDGE
114: */
115: Auto,
116: /**
117: * @see javax.jms.Session#CLIENT_ACKNOWLEDGE
118: */
119: Client,
120: /**
121: * @see javax.jms.Session#DUPS_OK_ACKNOWLEDGE
122: */
123: DupsOk
124: };
125:
126: /**
127: * Indicates the JMSCorrelationID message header.
128: *
129: * @deprecated
130: * @see HeaderType#JMSCorrelationID
131: */
132: public static final String HEADER_CORRELATIONID = HeaderType.JMSCorrelationID
133: .toString();
134:
135: /**
136: * Indicates the JMSDeliveryMode message header.
137: *
138: * @deprecated
139: * @see HeaderType#JMSDeliveryMode
140: */
141: public static final String HEADER_DELIVERYMODE = HeaderType.JMSDeliveryMode
142: .toString();
143:
144: /**
145: * Indicates the JMSExpiration message header.
146: * Use with the getHeaders and setHeaders methods.
147: *
148: * @deprecated
149: * @see HeaderType#JMSExpiration
150: */
151: public static final String HEADER_EXPIRATION = HeaderType.JMSExpiration
152: .toString();
153:
154: /**
155: * Indicates the JMSMessageID message header.
156: *
157: * @deprecated
158: * @see HeaderType#JMSMessageID
159: */
160: public static final String HEADER_MESSAGEID = HeaderType.JMSMessageID
161: .toString();
162:
163: /**
164: * Indicates the JMSPriority message header.
165: *
166: * @deprecated
167: * @see HeaderType#JMSPriority
168: */
169: public static final String HEADER_PRIORITY = HeaderType.JMSPriority
170: .toString();
171:
172: /**
173: * Indicates the JMSRedelivered message header.
174: *
175: * @deprecated
176: * @see HeaderType#JMSRedelivered
177: */
178: public static final String HEADER_REDELIVERED = HeaderType.JMSRedelivered
179: .toString();
180:
181: /**
182: * Indicates the JMSTimestamp message header.
183: *
184: * @deprecated
185: * @see HeaderType#JMSTimestamp
186: */
187: public static final String HEADER_TIMESTAMP = HeaderType.JMSTimestamp
188: .toString();
189:
190: /**
191: * Indicates the JMSType message header.
192: *
193: * @deprecated
194: * @see HeaderType#JMSType
195: */
196: public static final String HEADER_TYPE = HeaderType.JMSType
197: .toString();
198:
199: /**
200: * Get the {@link Session}.
201: * @return the session.
202: */
203: public Session getSession() throws ControlException;
204:
205: /**
206: * Get the {@link javax.jms.Connection}.
207: *
208: * @return the connection.
209: */
210: public javax.jms.Connection getConnection() throws ControlException;
211:
212: /**
213: * Get the {@link javax.jms.Destination}.
214: *
215: * @return an instance destination object.
216: */
217: public javax.jms.Destination getDestination()
218: throws ControlException;
219:
220: /**
221: * Sets the JMS headers to be assigned to the next JMS message
222: * sent. Note that these headers are set only on the next message,
223: * subsequent messages will not get these headers. Also note that
224: * if the body is a message itself,
225: * then any header set through this map will override headers set
226: * in the message.
227: *
228: * @param headers A map of header names (Strings or HeaderType) to header values.
229: */
230: public void setHeaders(Map headers);
231:
232: /**
233: * Sets a JMS header to be assigned to the next JMS message
234: * sent. Note that this headers is set only on the next message,
235: * subsequent messages will not get this header. Also note that
236: * if the body is a message itself,
237: * then the header set here will override the header set
238: * in the message.
239: *
240: * @param type the header type.
241: * @param value the value for the header.
242: */
243: public void setHeader(JMSControl.HeaderType type, Object value);
244:
245: /**
246: * Sets the JMS properties to be assigned to the next JMS message
247: * sent. Note that these properties are set only on the next
248: * message, subsequent messages will not get these
249: * properties. Also note that if the next message is sent through
250: * a publish method, then any property set through this
251: * map will override properties set in the message itself.
252: *
253: * @param properties A map of property names (Strings) to property
254: * values.
255: */
256: public void setProperties(Map properties);
257:
258: /**
259: * Set the given JMS property to be assigned to the next JMS message sent. Note that
260: * this property is set only on the next message, subsequent messages will not get this
261: * property. Also note that if the body is a message itself, then the property set here
262: * will override the property set in the message.
263: *
264: * @param name the property name.
265: * @param value the property value.
266: */
267: public void setProperty(String name, Object value);
268:
269: /**
270: * The message type used by the method. The default is to use the type of the body parameter.
271: */
272: @PropertySet(prefix="Message")
273: @Target({ElementType.METHOD})
274: @Retention(RetentionPolicy.RUNTIME)
275: public @interface Message {
276: @FeatureInfo(shortDescription="The message type")
277: public JMSControl.MessageType value() default JMSControl.MessageType.Auto;
278: }
279:
280: /**
281: * The method parameter representing a message property with the given name.
282: * For more information, see the property getter and setter methods on {@link Message}.
283: */
284: @Target({ElementType.PARAMETER})
285: @Retention(RetentionPolicy.RUNTIME)
286: public @interface Property {
287: /**
288: * The property name.
289: */
290: public String name();
291: }
292:
293: /**
294: * The method parameter representing a message property with the given name and value.
295: * For more information, see the property getter and setter methods on {@link Message}.
296: */
297: @PropertySet(prefix="Property")
298: @Target({ElementType.METHOD})
299: @Retention(RetentionPolicy.RUNTIME)
300: public @interface PropertyValue {
301: /**
302: * The property name.
303: */
304: public String name();
305:
306: /**
307: * The property value.
308: */
309: public String value();
310:
311: /**
312: * The property type.
313: */
314: public Class type() default String.class;
315:
316: }
317:
318: /**
319: * The method/parameter annotation representing a message priority. If not given
320: * then the default for the JMS provider is used.
321: */
322: @PropertySet(prefix="Priority")
323: @Target({ElementType.PARAMETER,ElementType.METHOD})
324: @Retention(RetentionPolicy.RUNTIME)
325: @AnnotationConstraints.AllowExternalOverride
326: public @interface Priority {
327: @AnnotationMemberTypes.Optional
328: public int value() default -1;
329: }
330:
331: /**
332: * The method/parameter representing the message JMS type.
333: */
334: @PropertySet(prefix="Type")
335: @Target({ElementType.PARAMETER,ElementType.METHOD})
336: @Retention(RetentionPolicy.RUNTIME)
337: public @interface Type {
338: public String value() default "";
339: }
340:
341: /**
342: * The method/parameter representing the message JMS CorrelationID.
343: */
344: @PropertySet(prefix="CorrelationId")
345: @Target({ElementType.PARAMETER,ElementType.METHOD})
346: @Retention(RetentionPolicy.RUNTIME)
347: public @interface CorrelationId {
348: public String value() default "";
349: }
350:
351: /**
352: * The method parameter representing a message expiration in milliseconds.
353: * If not given then the default for the JMS provider is used.
354: */
355: @PropertySet(prefix="Expiration")
356: @Target({ElementType.PARAMETER,ElementType.METHOD})
357: @Retention(RetentionPolicy.RUNTIME)
358: @AnnotationConstraints.AllowExternalOverride
359: public @interface Expiration {
360: @AnnotationMemberTypes.Optional
361: public long value() default -1L;
362: }
363:
364: /**
365: * The method parameter representing a message delivery mode.
366: * If not given then the default for the JMS provider is used.
367: */
368: @PropertySet(prefix="Delivery")
369: @Target({ElementType.PARAMETER,ElementType.METHOD})
370: @Retention(RetentionPolicy.RUNTIME)
371: public @interface Delivery {
372: public JMSControl.DeliveryMode value() default JMSControl.DeliveryMode.Auto;
373: }
374:
375: /**
376: * The method parameter representing one or more properties.
377: */
378: @PropertySet(prefix="Properties")
379: @Target({ElementType.METHOD})
380: @Retention(RetentionPolicy.RUNTIME)
381: public @interface Properties {
382: public PropertyValue[] value();
383: }
384:
385: /**
386: * The JMS destination annotation for a extended class method.
387: */
388: @PropertySet
389: @Retention(RetentionPolicy.RUNTIME)
390: @Target({ElementType.TYPE,ElementType.FIELD})
391: @AnnotationConstraints.AllowExternalOverride
392: public @interface Destination {
393: /**
394: * The JNDI name of the queue or topic.
395: */
396: // BUG: There should be a JMS_TOPIC_OR_QUEUE resource type.
397: @FeatureInfo(shortDescription="JNDI name of the queue or topic")
398: @AnnotationMemberTypes.JndiName(resourceType=AnnotationMemberTypes.JndiName.ResourceType.OTHER)
399: public String sendJndiName();
400:
401: /**
402: * The Correlation-Id for messages.
403: */
404: @FeatureInfo(shortDescription="Correlation-Id for messages")
405: @AnnotationMemberTypes.Optional
406: public String sendCorrelationProperty() default "";
407:
408: /**
409: * The JNDI name of queue connection factory.
410: */
411: @FeatureInfo(shortDescription="JNDI name of queue connection factory")
412: public String jndiConnectionFactory();
413:
414: /**
415: * The destination type (DestinationType). The default is to use the type of the destination object named by the JNDI name.
416: */
417: @FeatureInfo(shortDescription="The destination type (DestinationType). The default is to use the type of the destination object named by the JNDI name")
418: @AnnotationMemberTypes.Optional
419: public JMSControl.DestinationType sendType() default JMSControl.DestinationType.Auto;
420:
421: /**
422: * True if send is transacted. The default is transacted.
423: */
424: @FeatureInfo(shortDescription="True if send is transacted. The default is transacted")
425: @AnnotationMemberTypes.Optional
426: public boolean transacted() default true;
427:
428: /**
429: * The acknowledge mode. The default is to use auto-acknowledge.
430: */
431: @FeatureInfo(shortDescription="The acknowledge mode. The default is to use auto-acknowledge")
432: @AnnotationMemberTypes.Optional
433: public JMSControl.AcknowledgeMode acknowledgeMode() default JMSControl.AcknowledgeMode.Auto;
434:
435: /**
436: * The JNDI context factory.
437: */
438: @FeatureInfo(shortDescription="JNDI context factory")
439: @AnnotationMemberTypes.Optional
440: public String jndiContextFactory() default "";
441:
442: /**
443: * The JNDI provider URL.
444: */
445: @FeatureInfo(shortDescription="JNDI provider URL")
446: @AnnotationMemberTypes.Optional
447: @AnnotationMemberTypes.URI
448: public String jndiProviderURL() default "";
449:
450: /**
451: * The JNDI security principal.
452: */
453: @FeatureInfo(shortDescription="JNDI security principal")
454: @AnnotationMemberTypes.Optional
455: public String jndiUsername() default "";
456:
457: /**
458: * The JNDI security credentials.
459: */
460: @FeatureInfo(shortDescription="JNDI security credentials")
461: @AnnotationMemberTypes.Optional
462: public String jndiPassword() default "";
463: }
464: }
|