001    package 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     */
027    public 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    }