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 org.apache.servicemix.jbi.audit;
018
019 import javax.jbi.JBIException;
020 import javax.jbi.management.LifeCycleMBean;
021 import javax.jbi.messaging.MessageExchange;
022
023 /**
024 * Main interface for ServiceMix auditor.
025 * This interface may be used to view and delete exchanges
026 * or to re-send an exchange on behalf of the component that
027 * initiated the exchange.
028 *
029 * The implementation is free to offer additional features for
030 * selecting message exchanges which are dependant of the underlying
031 * store.
032 *
033 * @author Guillaume Nodet (gnt)
034 * @since 2.1
035 * @version $Revision: 34165 $
036 */
037 public interface AuditorMBean extends LifeCycleMBean {
038
039 /**
040 * Get the number of exchanges stored by this auditor.
041 *
042 * @return the number of exchanges stored
043 * @throws AuditorException if an error occurs accessing the data store.
044 */
045 int getExchangeCount() throws AuditorException;
046
047 /**
048 * Retrieve the exchange id of the exchange at the specified index.
049 * Index must be a null or positive integer.
050 * If index is greater than the number of exchanges stored,
051 * a null string should be returned.
052 *
053 * @param index the index of the exchange
054 * @return the exchange id, or null of index is greater than the exchange count
055 * @throws AuditorException if an error occurs accessing the data store.
056 * @throws IllegalArgumentException if index is less than zero
057 */
058 String getExchangeIdByIndex(int index) throws AuditorException;
059
060 /**
061 * Retrieve all exchanges ids from the data store.
062 *
063 * @return an array of exchange ids
064 * @throws AuditorException if an error occurs accessing the data store.
065 */
066 String[] getAllExchangeIds() throws AuditorException;
067
068 /**
069 * Retrieve a range of message exchange ids.
070 * The ids retrieved range from fromIndex (inclusive) to
071 * toIndex (exclusive).
072 * If fromIndex == toIndex, an empty array must be returned.
073 * If fromIndex is less than zero, or if toIndex is less than
074 * fromIndex, an exception will be thrown.
075 * An array of exactly (toIndex - fromIndex) element should be
076 * returned.
077 * This array must be filled by null, for indexes that are greater
078 * than the number of exchanges stored.
079 *
080 * @param fromIndex the lower bound index of the ids to be retrieved.
081 * fromIndex must be greater or equal to zero.
082 * @param toIndex the upper bound (exclusive) of the ids to be retrieved.
083 * toIndex must be greater or equal to fromIndex
084 * @return an array of exchange ids
085 * @throws AuditorException if an error occurs accessing the data store.
086 * @throws IllegalArgumentException if fromIndex is less than zero or if toIndex is
087 * less than fromIndex.
088 */
089 String[] getExchangeIdsByRange(int fromIndex, int toIndex) throws AuditorException;
090
091 /**
092 * Retrieve the exchange at the specified index.
093 * Index must be a null or positive integer, and should be less than
094 * the current exchange count stored.
095 * If index is greater than the number of exchanges stored,
096 * a null exchange should be returned.
097 *
098 * @param index the index of the exchange
099 * @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 getExchangeByIndex(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 getExchangeById(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[] getAllExchanges() 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[] getExchangesByRange(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[] getExchangesByIds(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 deleteAllExchanges() 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 deleteExchangeByIndex(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 deleteExchangeById(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 deleteExchangesByRange(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 deleteExchangesByIds(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 }