AuditorMBean


1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.servicemix.jbi.audit;
18  
19  import javax.jbi.JBIException;
20  import javax.jbi.management.LifeCycleMBean;
21  import javax.jbi.messaging.MessageExchange;
22  
23  /**
24   * Main interface for ServiceMix auditor.
25   * This interface may be used to view and delete exchanges
26   * or to re-send an exchange on behalf of the component that
27   * initiated the exchange. 
28   * 
29   * The implementation is free to offer additional features for
30   * selecting message exchanges which are dependant of the underlying
31   * store.
32   * 
33   * @author Guillaume Nodet (gnt)
34   * @since 2.1
35   * @version $Revision: 426415 $
36   */
37  public interface AuditorMBean extends LifeCycleMBean {
38  
39      /**
40       * Get the number of exchanges stored by this auditor.
41       * 
42       * @return the number of exchanges stored 
43       * @throws AuditorException if an error occurs accessing the data store.
44       */
45      int getExchangeCount() throws AuditorException;
46      
47      /**
48       * Retrieve the exchange id of the exchange at the specified index.
49       * Index must be a null or positive integer.
50       * If index is greater than the number of exchanges stored,
51       * a null string should be returned.
52       * 
53       * @param index the index of the exchange
54       * @return the exchange id, or null of index is greater than the exchange count
55       * @throws AuditorException if an error occurs accessing the data store.
56       * @throws IllegalArgumentException if index is less than zero
57       */
58      String   getExchangeId(int index) throws AuditorException;
59      
60      /**
61       * Retrieve all exchanges ids from the data store.
62       * 
63       * @return an array of exchange ids
64       * @throws AuditorException if an error occurs accessing the data store.
65       */
66      String  [] getExchangeIds() throws AuditorException;
67      
68      /**
69       * Retrieve a range of message exchange ids.
70       * The ids retrieved range from fromIndex (inclusive) to
71       * toIndex (exclusive).
72       * If fromIndex == toIndex, an empty array must be returned.
73       * If fromIndex is less than zero, or if toIndex is less than
74       * fromIndex, an exception will be thrown.
75       * An array of exactly (toIndex - fromIndex) element should be
76       * returned.
77       * This array must be filled by null, for indexes that are greater
78       * than the number of exchanges stored.
79       * 
80       * @param fromIndex the lower bound index of the ids to be retrieved.
81       *                  fromIndex must be greater or equal to zero.
82       * @param toIndex the upper bound (exclusive) of the ids to be retrieved.
83       *                toIndex must be greater or equal to fromIndex
84       * @return an array of exchange ids
85       * @throws AuditorException if an error occurs accessing the data store.
86       * @throws IllegalArgumentException if fromIndex is less than zero or if toIndex is 
87       *                                  less than fromIndex.
88       */
89      String  [] getExchangeIds(int fromIndex, int toIndex)  throws AuditorException;
90      
91      /**
92       * Retrieve the exchange at the specified index.
93       * Index must be a null or positive integer, and should be less than
94       * the current exchange count stored. 
95       * If index is greater than the number of exchanges stored,
96       * a null exchange should be returned.
97       * 
98       * @param index the index of the exchange
99       * @return the exchange, or null of index is greater than the exchange count
100      * @throws AuditorException if an error occurs accessing the data store.
101      * @throws IllegalArgumentException if index is less than zero
102      */
103     MessageExchange getExchange(int index) throws AuditorException;
104     
105     /**
106      * Retrieve the exchange for a specified id.
107      * Id must be non null and non empty. 
108      * If the exchange with the specified id is not found, null should be returned.
109      * 
110      * @param id the id of the exchange
111      * @return the exchange with the specified id, or null if not found
112      * @throws AuditorException if an error occurs accessing the data store.
113      * @throws IllegalArgumentException if id is null or empty 
114      */
115     MessageExchange getExchange(String   id) throws AuditorException;
116     
117     /**
118      * Retrieve all exchanges =from the data store.
119      * 
120      * @return an array of exchange
121      * @throws AuditorException if an error occurs accessing the data store.
122      */
123     MessageExchange[] getExchanges() throws AuditorException;
124     
125     /**
126      * Retrieve a range of message exchange.
127      * The exchanges retrieved range from fromIndex (inclusive) to
128      * toIndex (exclusive).
129      * If fromIndex == toIndex, an empty array must be returned.
130      * If fromIndex is less than zero, or if toIndex is less than
131      * fromIndex, an exception will be thrown.
132      * An array of exactly (toIndex - fromIndex) element should be
133      * returned.
134      * This array must be filled by null, for indexes that are greater
135      * than the number of exchanges stored.
136      * 
137      * @param fromIndex the lower bound index of the exchanges to be retrieved.
138      *                  fromIndex must be greater or equal to zero.
139      * @param toIndex the upper bound (exclusive) of the exchanges to be retrieved.
140      *                toIndex must be greater or equal to fromIndex
141      * @return an array of exchange
142      * @throws AuditorException if an error occurs accessing the data store.
143      * @throws IllegalArgumentException if fromIndex is less than zero or if toIndex is 
144      *                                  less than fromIndex.
145      */
146     MessageExchange[] getExchanges(int fromIndex, int toIndex) throws AuditorException;
147 
148     /**
149      * Retrieve exchanges for the specified ids.
150      * An array of exactly ids.length elements must be returned.
151      * This array should be filled with null for exchanges that
152      * have not been found in the store. 
153      * 
154      * @param ids the ids of exchanges to retrieve
155      * @return an array of exchanges
156      * @throws AuditorException if an error occurs accessing the data store.
157      * @throws IllegalArgumentException if ids is null, or one of its
158      *         element is null or empty.
159      */
160     MessageExchange[] getExchanges(String  [] ids) throws AuditorException;
161     
162     /**
163      * Delete all exchanges =from the data store.
164      * 
165      * @return the number of exchanges deleted, or -1 if such information
166      *         can not be provided
167      * @throws AuditorException if an error occurs accessing the data store.
168      */
169     int deleteExchanges() throws AuditorException;
170     
171     /**
172      * Delete a message, given its index.
173      * Index must be a null or positive integer, and should be less than
174      * the current exchange count stored. 
175      * If index is greater than the number of exchanges stored,
176      * false should be returned.
177      * 
178      * @param index the index of the exchange
179      * @return true if the exchange has been successfully deleted,
180      *         false if index is greater than the number of exchanges stored
181      * @throws AuditorException if an error occurs accessing the data store.
182      * @throws IllegalArgumentException if index is less than zero
183      */
184     boolean deleteExchange(int index) throws AuditorException;
185     
186     /**
187      * Delete the exchange with the specified id.
188      * Id must be non null and non empty.
189      * 
190      * @param id the id of the exchange to delete
191      * @return true if the exchange has been successfully deleted,
192      *         false if the exchange was not found
193      * @throws AuditorException if an error occurs accessing the data store.
194      * @throws IllegalArgumentException if id is null or empty 
195      */
196     boolean deleteExchange(String   id) throws AuditorException;
197 
198     /**
199      * Delete exchanges ranging from fromIndex to toIndex.
200      * 
201      * @param fromIndex the lower bound index of the exchanges to be retrieved.
202      *                  fromIndex must be greater or equal to zero.
203      * @param toIndex the upper bound (exclusive) of the exchanges to be retrieved.
204      *                toIndex must be greater or equal to fromIndex
205      * @return the number of exchanges deleted
206      * @throws AuditorException if an error occurs accessing the data store.
207      * @throws IllegalArgumentException if fromIndex is less than zero or if toIndex is 
208      *                                  less than fromIndex.
209      */
210     int deleteExchanges(int fromIndex, int toIndex) throws AuditorException;
211 
212     /**
213      * Delete exchanges given their ids.
214      * 
215      * @param ids the ids of exchanges to retrieve
216      * @return an array of exchanges
217      * @return the number of exchanges deleted
218      * @throws AuditorException if an error occurs accessing the data store.
219      * @throws IllegalArgumentException if ids is null, or one of its
220      *         element is null or empty.
221      */
222     int deleteExchanges(String  [] ids) throws AuditorException;
223 
224     /**
225      * Resend an exchange on behalf of the consumer component that initiated this exchange.
226      * The exchange must have been retrieved from this auditor, else the behavior
227      * is undefined.
228      * The exchange will be given a new id and will be reset to its original state:
229      * the out and fault messages will be removed (if they exist), the error will be
230      * set to null, state to ACTIVE.
231      * The consumer component must be prepared
232      * to receive a response or a DONE status to an exchange it did not 
233      * have directly initiated.
234      * 
235      * @param exchange the exchange to be sent
236      * @throws JBIException if an error occurs re-sending the exchange
237      */
238     void resendExchange(MessageExchange exchange)throws JBIException;
239 }
240
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags