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: 492738 $
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)
090: throws AuditorException;
091:
092: /**
093: * Retrieve the exchange at the specified index.
094: * Index must be a null or positive integer, and should be less than
095: * the current exchange count stored.
096: * If index is greater than the number of exchanges stored,
097: * a null exchange should be returned.
098: *
099: * @param index the index of the exchange
100: * @return the exchange, or null of index is greater than the exchange count
101: * @throws AuditorException if an error occurs accessing the data store.
102: * @throws IllegalArgumentException if index is less than zero
103: */
104: MessageExchange getExchangeByIndex(int index)
105: throws AuditorException;
106:
107: /**
108: * Retrieve the exchange for a specified id.
109: * Id must be non null and non empty.
110: * If the exchange with the specified id is not found, null should be returned.
111: *
112: * @param id the id of the exchange
113: * @return the exchange with the specified id, or null if not found
114: * @throws AuditorException if an error occurs accessing the data store.
115: * @throws IllegalArgumentException if id is null or empty
116: */
117: MessageExchange getExchangeById(String id) throws AuditorException;
118:
119: /**
120: * Retrieve all exchanges =from the data store.
121: *
122: * @return an array of exchange
123: * @throws AuditorException if an error occurs accessing the data store.
124: */
125: MessageExchange[] getAllExchanges() throws AuditorException;
126:
127: /**
128: * Retrieve a range of message exchange.
129: * The exchanges retrieved range from fromIndex (inclusive) to
130: * toIndex (exclusive).
131: * If fromIndex == toIndex, an empty array must be returned.
132: * If fromIndex is less than zero, or if toIndex is less than
133: * fromIndex, an exception will be thrown.
134: * An array of exactly (toIndex - fromIndex) element should be
135: * returned.
136: * This array must be filled by null, for indexes that are greater
137: * than the number of exchanges stored.
138: *
139: * @param fromIndex the lower bound index of the exchanges to be retrieved.
140: * fromIndex must be greater or equal to zero.
141: * @param toIndex the upper bound (exclusive) of the exchanges to be retrieved.
142: * toIndex must be greater or equal to fromIndex
143: * @return an array of exchange
144: * @throws AuditorException if an error occurs accessing the data store.
145: * @throws IllegalArgumentException if fromIndex is less than zero or if toIndex is
146: * less than fromIndex.
147: */
148: MessageExchange[] getExchangesByRange(int fromIndex, int toIndex)
149: throws AuditorException;
150:
151: /**
152: * Retrieve exchanges for the specified ids.
153: * An array of exactly ids.length elements must be returned.
154: * This array should be filled with null for exchanges that
155: * have not been found in the store.
156: *
157: * @param ids the ids of exchanges to retrieve
158: * @return an array of exchanges
159: * @throws AuditorException if an error occurs accessing the data store.
160: * @throws IllegalArgumentException if ids is null, or one of its
161: * element is null or empty.
162: */
163: MessageExchange[] getExchangesByIds(String[] ids)
164: throws AuditorException;
165:
166: /**
167: * Delete all exchanges =from the data store.
168: *
169: * @return the number of exchanges deleted, or -1 if such information
170: * can not be provided
171: * @throws AuditorException if an error occurs accessing the data store.
172: */
173: int deleteAllExchanges() throws AuditorException;
174:
175: /**
176: * Delete a message, given its index.
177: * Index must be a null or positive integer, and should be less than
178: * the current exchange count stored.
179: * If index is greater than the number of exchanges stored,
180: * false should be returned.
181: *
182: * @param index the index of the exchange
183: * @return true if the exchange has been successfully deleted,
184: * false if index is greater than the number of exchanges stored
185: * @throws AuditorException if an error occurs accessing the data store.
186: * @throws IllegalArgumentException if index is less than zero
187: */
188: boolean deleteExchangeByIndex(int index) throws AuditorException;
189:
190: /**
191: * Delete the exchange with the specified id.
192: * Id must be non null and non empty.
193: *
194: * @param id the id of the exchange to delete
195: * @return true if the exchange has been successfully deleted,
196: * false if the exchange was not found
197: * @throws AuditorException if an error occurs accessing the data store.
198: * @throws IllegalArgumentException if id is null or empty
199: */
200: boolean deleteExchangeById(String id) throws AuditorException;
201:
202: /**
203: * Delete exchanges ranging from fromIndex to toIndex.
204: *
205: * @param fromIndex the lower bound index of the exchanges to be retrieved.
206: * fromIndex must be greater or equal to zero.
207: * @param toIndex the upper bound (exclusive) of the exchanges to be retrieved.
208: * toIndex must be greater or equal to fromIndex
209: * @return the number of exchanges deleted
210: * @throws AuditorException if an error occurs accessing the data store.
211: * @throws IllegalArgumentException if fromIndex is less than zero or if toIndex is
212: * less than fromIndex.
213: */
214: int deleteExchangesByRange(int fromIndex, int toIndex)
215: throws AuditorException;
216:
217: /**
218: * Delete exchanges given their ids.
219: *
220: * @param ids the ids of exchanges to retrieve
221: * @return an array of exchanges
222: * @return the number of exchanges deleted
223: * @throws AuditorException if an error occurs accessing the data store.
224: * @throws IllegalArgumentException if ids is null, or one of its
225: * element is null or empty.
226: */
227: int deleteExchangesByIds(String[] ids) throws AuditorException;
228:
229: /**
230: * Resend an exchange on behalf of the consumer component that initiated this exchange.
231: * The exchange must have been retrieved from this auditor, else the behavior
232: * is undefined.
233: * The exchange will be given a new id and will be reset to its original state:
234: * the out and fault messages will be removed (if they exist), the error will be
235: * set to null, state to ACTIVE.
236: * The consumer component must be prepared
237: * to receive a response or a DONE status to an exchange it did not
238: * have directly initiated.
239: *
240: * @param exchange the exchange to be sent
241: * @throws JBIException if an error occurs re-sending the exchange
242: */
243: void resendExchange(MessageExchange exchange) throws JBIException;
244: }
|