1 /* 2 * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. 3 */ 4 /* 5 * Licensed to the Apache Software Foundation (ASF) under one or more 6 * contributor license agreements. See the NOTICE file distributed with 7 * this work for additional information regarding copyright ownership. 8 * The ASF licenses this file to You under the Apache License, Version 2.0 9 * (the "License"); you may not use this file except in compliance with 10 * the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 package org.apache.qetest; 21 22 /** 23 * Base class defining common functionality of logging handlers. 24 * <p> 25 * Common functionality used for testing when implementing various Handlers and 26 * Listeners. Provides common ways to set Loggers and levels, reset, and set 27 * expected errors or the like. Likely used to implement testing wrapper classes 28 * for things like javax.xml.transform.ErrorListener and 29 * org.xml.sax.ErrorHandler</p> 30 * <p> 31 * The best description for this class can be seen in an example; see 32 * trax.LoggingErrorHandler.java for one.</p> 33 */ 34 public interface CheckingHandler { 35 /** 36 * Reset any items or counters we've handled. Resets any data about what 37 * we've handled or logged so far, like getLast() and getCounters() data, as 38 * well as any expected items from setExpected(). Does not change our Logger 39 * or loggingLevel. 40 */ 41 public void reset(); 42 43 /** 44 * Ask us to report checkPass/Fail for certain events we handle. Since we 45 * may have to handle many events between when a test will be able to call 46 * us, testers can set this to have us automatically call checkPass when we 47 * see an item that matches, or to call checkFail when we get an unexpected 48 * item. Generally, we only call check* methods when: 49 * <ul> 50 * <li>containsString is not set, reset, or is ITEM_DONT_CARE, we do nothing 51 * (i.e. never call check* for this item)</li> 52 * <li>containsString is ITEM_CHECKFAIL, we will always call checkFail with 53 * the contents of any item if it occurs</li> 54 * <li>containsString is anything else, we will grab a String representation 55 * of every item of that type that comes along, and if the containsString is 56 * found, case-sensitive, within the handled item's string, call checkPass, 57 * otherwise call checkFail</li> 58 * </ul> 59 * Note that most implementations will only validate the first event of a 60 * specific type, and then will reset validation for that event type. This 61 * is because many events may be raised in between the time that a calling 62 * Test class could tell us of the 'next' expected event. 63 * 64 * @param itemType which of the various types of items we might handle; 65 * should be defined as a constant by subclasses 66 * @param expectation a set expectation if we care this event or not. 67 */ 68 public void setExpected(int itemType, Expectation expectation); 69 70 enum Expectation { 71 ITEM_DONT_CARE, 72 ITEM_CHECKFAIL, 73 ITEM_CHECKPASS, 74 ITEM_RESOLVE 75 } 76 }