001package org.apache.commons.digester3.binder;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022/**
023 * The Digester EDSL.
024 *
025 * @since 3.0
026 */
027public interface RulesBinder
028{
029
030    /**
031     * Returns the context {@code ClassLoader}.
032     *
033     * @return The context {@code ClassLoader}
034     */
035    ClassLoader getContextClassLoader();
036
037    /**
038     * Records an error message which will be presented to the user at a later time. Unlike throwing an exception, this
039     * enable us to continue configuring the Digester and discover more errors. Uses
040     * {@link String#format(String, Object[])} to insert the arguments into the message.
041     *
042     * @param messagePattern The message string pattern
043     * @param arguments Arguments referenced by the format specifiers in the format string
044     */
045    void addError( String messagePattern, Object... arguments );
046
047    /**
048     * Records an exception, the full details of which will be logged, and the message of which will be presented to the
049     * user at a later time. If your Module calls something that you worry may fail, you should catch the exception and
050     * pass it into this.
051     *
052     * @param t The exception has to be recorded.
053     */
054    void addError( Throwable t );
055
056    /**
057     * Allows sub-modules inclusion while binding rules.
058     *
059     * @param rulesModule the sub-module has to be included.
060     */
061    void install( RulesModule rulesModule );
062
063    /**
064     * Allows to associate the given pattern to one or more Digester rules.
065     *
066     * @param pattern The pattern that this rule should match
067     * @return The Digester rules builder
068     */
069    LinkedRuleBuilder forPattern( String pattern );
070
071}