001/*
002 * ModeShape (http://www.modeshape.org)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *       http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.modeshape.common.collection;
017
018import java.io.Serializable;
019import java.util.EnumSet;
020import java.util.Iterator;
021import org.modeshape.common.collection.Problem.Status;
022import org.modeshape.common.function.Consumer;
023import org.modeshape.common.i18n.I18n;
024import org.modeshape.common.logging.Logger;
025
026/**
027 * An interface for a collection of {@link Problem} objects, with multiple overloaded methods for adding errors, warnings, and
028 * informational messages.
029 */
030public interface Problems extends Iterable<Problem>, Serializable {
031
032    /**
033     * Add an error message with the parameters that should be used when localizing the message.
034     * 
035     * @param message the internationalized message describing the problem
036     * @param params the values for the parameters in the message
037     */
038    void addError( I18n message,
039                   Object... params );
040
041    /**
042     * Add an error exception and message with the parameters that should be used when localizing the message.
043     * 
044     * @param throwable the exception that represents the error; may be null
045     * @param message the internationalized message describing the problem
046     * @param params the values for the parameters in the message
047     */
048    void addError( Throwable throwable,
049                   I18n message,
050                   Object... params );
051
052    /**
053     * Add an error message with a description of the resource, its location, and the parameters that should be used when
054     * localizing the message
055     * 
056     * @param resource the description of the resource; may be null
057     * @param location the location of the resource; may be null
058     * @param message the internationalized message describing the problem
059     * @param params the values for the parameters in the message
060     */
061    void addError( String resource,
062                   String location,
063                   I18n message,
064                   Object... params );
065
066    /**
067     * Add an error exception and message with a description of the resource, its location, and the parameters that should be used
068     * when localizing the message
069     * 
070     * @param throwable the exception that represents the error; may be null
071     * @param resource the description of the resource; may be null
072     * @param location the location of the resource; may be null
073     * @param message the internationalized message describing the problem
074     * @param params the values for the parameters in the message
075     */
076    void addError( Throwable throwable,
077                   String resource,
078                   String location,
079                   I18n message,
080                   Object... params );
081
082    /**
083     * Add an error message with the parameters that should be used when localizing the message.
084     * 
085     * @param code the error code
086     * @param message the internationalized message describing the problem
087     * @param params the values for the parameters in the message
088     */
089    void addError( int code,
090                   I18n message,
091                   Object... params );
092
093    /**
094     * Add an error exception and message with the parameters that should be used when localizing the message.
095     * 
096     * @param throwable the exception that represents the error; may be null
097     * @param code the error code
098     * @param message the internationalized message describing the problem
099     * @param params the values for the parameters in the message
100     */
101    void addError( Throwable throwable,
102                   int code,
103                   I18n message,
104                   Object... params );
105
106    /**
107     * Add an error message with a description of the resource, its location, and the parameters that should be used when
108     * localizing the message
109     * 
110     * @param code the error code
111     * @param resource the description of the resource; may be null
112     * @param location the location of the resource; may be null
113     * @param message the internationalized message describing the problem
114     * @param params the values for the parameters in the message
115     */
116    void addError( int code,
117                   String resource,
118                   String location,
119                   I18n message,
120                   Object... params );
121
122    /**
123     * Add an error exception and message with a description of the resource, its location, and the parameters that should be used
124     * when localizing the message
125     * 
126     * @param throwable the exception that represents the error; may be null
127     * @param code the error code
128     * @param resource the description of the resource; may be null
129     * @param location the location of the resource; may be null
130     * @param message the internationalized message describing the problem
131     * @param params the values for the parameters in the message
132     */
133    void addError( Throwable throwable,
134                   int code,
135                   String resource,
136                   String location,
137                   I18n message,
138                   Object... params );
139
140    /**
141     * Add a warning message with the parameters that should be used when localizing the message.
142     * 
143     * @param message the internationalized message describing the problem
144     * @param params the values for the parameters in the message
145     */
146    void addWarning( I18n message,
147                     Object... params );
148
149    /**
150     * Add a warning exception and message with the parameters that should be used when localizing the message.
151     * 
152     * @param throwable the exception that represents the error; may be null
153     * @param message the internationalized message describing the problem
154     * @param params the values for the parameters in the message
155     */
156    void addWarning( Throwable throwable,
157                     I18n message,
158                     Object... params );
159
160    /**
161     * Add a warning message with a description of the resource, its location, and the parameters that should be used when
162     * localizing the message
163     * 
164     * @param resource the description of the resource; may be null
165     * @param location the location of the resource; may be null
166     * @param message the internationalized message describing the problem
167     * @param params the values for the parameters in the message
168     */
169    void addWarning( String resource,
170                     String location,
171                     I18n message,
172                     Object... params );
173
174    /**
175     * Add a warning exception and message with a description of the resource, its location, and the parameters that should be
176     * used when localizing the message
177     * 
178     * @param throwable the exception that represents the warning; may be null
179     * @param resource the description of the resource; may be null
180     * @param location the location of the resource; may be null
181     * @param message the internationalized message describing the problem
182     * @param params the values for the parameters in the message
183     */
184    void addWarning( Throwable throwable,
185                     String resource,
186                     String location,
187                     I18n message,
188                     Object... params );
189
190    /**
191     * Add a warning message with the parameters that should be used when localizing the message.
192     * 
193     * @param code the problem code
194     * @param message the internationalized message describing the problem
195     * @param params the values for the parameters in the message
196     */
197    void addWarning( int code,
198                     I18n message,
199                     Object... params );
200
201    /**
202     * Add a warning exception and message with the parameters that should be used when localizing the message.
203     * 
204     * @param throwable the exception that represents the warning; may be null
205     * @param code the problem code
206     * @param message the internationalized message describing the problem
207     * @param params the values for the parameters in the message
208     */
209    void addWarning( Throwable throwable,
210                     int code,
211                     I18n message,
212                     Object... params );
213
214    /**
215     * Add a warning message with a description of the resource, its location, and the parameters that should be used when
216     * localizing the message
217     * 
218     * @param code the problem code
219     * @param resource the description of the resource; may be null
220     * @param location the location of the resource; may be null
221     * @param message the internationalized message describing the problem
222     * @param params the values for the parameters in the message
223     */
224    void addWarning( int code,
225                     String resource,
226                     String location,
227                     I18n message,
228                     Object... params );
229
230    /**
231     * Add a warning exception and message with a description of the resource, its location, and the parameters that should be
232     * used when localizing the message
233     * 
234     * @param throwable the exception that represents the warning; may be null
235     * @param code the problem code
236     * @param resource the description of the resource; may be null
237     * @param location the location of the resource; may be null
238     * @param message the internationalized message describing the problem
239     * @param params the values for the parameters in the message
240     */
241    void addWarning( Throwable throwable,
242                     int code,
243                     String resource,
244                     String location,
245                     I18n message,
246                     Object... params );
247
248    /**
249     * Add a informational message with the parameters that should be used when localizing the message.
250     * 
251     * @param message the internationalized message describing the problem
252     * @param params the values for the parameters in the message
253     */
254    void addInfo( I18n message,
255                  Object... params );
256
257    /**
258     * Add an informational exception and message with the parameters that should be used when localizing the message.
259     * 
260     * @param throwable the exception that represents the warning; may be null
261     * @param message the internationalized message describing the problem
262     * @param params the values for the parameters in the message
263     */
264    void addInfo( Throwable throwable,
265                  I18n message,
266                  Object... params );
267
268    /**
269     * Add an informational message with a description of the resource, its location, and the parameters that should be used when
270     * localizing the message
271     * 
272     * @param resource the description of the resource; may be null
273     * @param location the location of the resource; may be null
274     * @param message the internationalized message describing the problem
275     * @param params the values for the parameters in the message
276     */
277    void addInfo( String resource,
278                  String location,
279                  I18n message,
280                  Object... params );
281
282    /**
283     * Add an informational exception and message with a description of the resource, its location, and the parameters that should
284     * be used when localizing the message
285     * 
286     * @param throwable the exception that represents the problem; may be null
287     * @param resource the description of the resource; may be null
288     * @param location the location of the resource; may be null
289     * @param message the internationalized message describing the problem
290     * @param params the values for the parameters in the message
291     */
292    void addInfo( Throwable throwable,
293                  String resource,
294                  String location,
295                  I18n message,
296                  Object... params );
297
298    /**
299     * Add a informational message with the parameters that should be used when localizing the message.
300     * 
301     * @param code the problem code
302     * @param message the internationalized message describing the problem
303     * @param params the values for the parameters in the message
304     */
305    void addInfo( int code,
306                  I18n message,
307                  Object... params );
308
309    /**
310     * Add a informational exception and message with the parameters that should be used when localizing the message.
311     * 
312     * @param throwable the exception that represents the warning; may be null
313     * @param code the problem code
314     * @param message the internationalized message describing the problem
315     * @param params the values for the parameters in the message
316     */
317    void addInfo( Throwable throwable,
318                  int code,
319                  I18n message,
320                  Object... params );
321
322    /**
323     * Add an informational message with a description of the resource, its location, and the parameters that should be used when
324     * localizing the message
325     * 
326     * @param code the problem code
327     * @param resource the description of the resource; may be null
328     * @param location the location of the resource; may be null
329     * @param message the internationalized message describing the problem
330     * @param params the values for the parameters in the message
331     */
332    void addInfo( int code,
333                  String resource,
334                  String location,
335                  I18n message,
336                  Object... params );
337
338    /**
339     * Add an informational exception and message with a description of the resource, its location, and the parameters that should
340     * be used when localizing the message
341     * 
342     * @param throwable the exception that represents the problem; may be null
343     * @param code the problem code
344     * @param resource the description of the resource; may be null
345     * @param location the location of the resource; may be null
346     * @param message the internationalized message describing the problem
347     * @param params the values for the parameters in the message
348     */
349    void addInfo( Throwable throwable,
350                  int code,
351                  String resource,
352                  String location,
353                  I18n message,
354                  Object... params );
355
356    /**
357     * Add all of the problems in the supplied list.
358     * 
359     * @param problems the problems to add to this list; this method does nothing if null or empty
360     */
361    void addAll( Iterable<Problem> problems );
362
363    /**
364     * Get the number of problems that are in this collection
365     * 
366     * @return the number of problems; never negative
367     * @see #hasProblems()
368     * @see #isEmpty()
369     */
370    int size();
371
372    /**
373     * Determine if this collection is empty.
374     * 
375     * @return true if the there are no problems, or false if there is at least one
376     * @see #hasProblems()
377     * @see #size()
378     */
379    boolean isEmpty();
380
381    /**
382     * Determine if there are problems in this collection.
383     * 
384     * @return true if there is at least one problem, or false if it is empty
385     * @see #isEmpty()
386     * @see #size()
387     */
388    boolean hasProblems();
389
390    /**
391     * Determine if there is at least one error in this collection.
392     * 
393     * @return true if there is at least one error in this collection, or false if there are no errors
394     */
395    boolean hasErrors();
396
397    /**
398     * Determine if there is at least one warning in this collection.
399     * 
400     * @return true if there is at least one warning in this collection, or false if there are no warnings
401     */
402    boolean hasWarnings();
403
404    /**
405     * Determine if there is at least one informational problem in this collection.
406     * 
407     * @return true if there is at least one informational problem in this collection, or false if there are no informational
408     *         problems
409     */
410    boolean hasInfo();
411
412    /**
413     * Determine the number of errors within these results.
414     * 
415     * @return the number of errors; always 0 or a positive number
416     */
417    int errorCount();
418
419    /**
420     * Determine the number of warnings within these results.
421     * 
422     * @return the number of warnings; always 0 or a positive number
423     */
424    int warningCount();
425
426    /**
427     * Determine the number of information messages within these results.
428     * 
429     * @return the number of information messages; always 0 or a positive number
430     */
431    int infoCount();
432
433    /**
434     * Determine the number of problems (that is, errors and warnings) within these results.
435     * 
436     * @return the number of errors and warnings; always 0 or a positive number
437     */
438    int problemCount();
439
440    @Override
441    Iterator<Problem> iterator();
442
443    /**
444     * Apply the consumer to each of the problems. This method does nothing if the consumer is null.
445     *
446     * @param consumer the consumer, which operates with side effects
447     */
448    void apply( Consumer<Problem> consumer );
449
450    /**
451     * Apply the consumer to each of the problems with the supplied status. This method does nothing if the status or consumer are
452     * null.
453     *
454     * @param status the status of the problems to be consumed
455     * @param consumer the consumer, which operates with side effects
456     */
457    void apply( Status status,
458                Consumer<Problem> consumer );
459
460    /**
461     * Apply the consumer to each of the problems with the supplied status. This method does nothing if the status or consumer are
462     * null.
463     *
464     * @param statuses the statuses of the problems to be consumed
465     * @param consumer the consumer, which operates with side effects
466     */
467    void apply( EnumSet<Status> statuses,
468                Consumer<Problem> consumer );
469
470    /**
471     * Write the problems to the supplied logger.
472     *
473     * @param logger the logger
474     */
475    void writeTo( Logger logger );
476
477    /**
478     * Write the problems to the supplied logger.
479     *
480     * @param logger the logger
481     * @param firstStatus the first status to be logged
482     * @param additionalStatuses the additional statuses to be logged
483     */
484    void writeTo( Logger logger,
485                  Status firstStatus,
486                  Status... additionalStatuses );
487}