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     * A support class for RulesModule which reduces repetition and results in a more readable configuration.
024     *
025     * @since 3.0
026     */
027    public abstract class AbstractRulesModule
028        implements RulesModule
029    {
030    
031        private RulesBinder rulesBinder;
032    
033        /**
034         * {@inheritDoc}
035         */
036        public final void configure( RulesBinder rulesBinder )
037        {
038            if ( this.rulesBinder != null )
039            {
040                throw new IllegalStateException( "Re-entry is not allowed." );
041            }
042    
043            this.rulesBinder = rulesBinder;
044            try
045            {
046                configure();
047            }
048            finally
049            {
050                this.rulesBinder = null;
051            }
052        }
053    
054        /**
055         * Configures a {@link RulesBinder} via the exposed methods.
056         */
057        protected abstract void configure();
058    
059        /**
060         * Records an error message which will be presented to the user at a later time.
061         *
062         * Uses {@link java.lang.String#format(String, Object...)} to insert the arguments into the message.
063         *
064         * @param messagePattern A
065         *        <a href="http://download.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax">format string</a>
066         * @param arguments Arguments referenced by the format specifiers in the format string
067         * @see RulesBinder#addError(String, Object...)
068         */
069        protected void addError( String messagePattern, Object... arguments )
070        {
071            rulesBinder.addError( messagePattern, arguments );
072        }
073    
074        /**
075         * Records an exception, the full details of which will be logged, and the message of which will be presented to
076         * the user at a later time.
077         *
078         * @param t The exception has to be recorded
079         * @see RulesBinder#addError(Throwable)
080         */
081        protected void addError( Throwable t )
082        {
083            rulesBinder.addError( t );
084        }
085    
086        /**
087         * Uses the given module to configure more bindings.
088         *
089         * @param rulesModule The module used to configure more bindings
090         * @see RulesBinder#install(RulesModule)
091         */
092        protected void install( RulesModule rulesModule )
093        {
094            rulesBinder.install( rulesModule );
095        }
096    
097        /**
098         * Allows user binding one or more Digester rules to the input pattern.
099         *
100         * @param pattern The pattern used to bind rules
101         * @return The Digester rules builder
102         * @see RulesBinder#forPattern(String)
103         */
104        protected LinkedRuleBuilder forPattern( String pattern )
105        {
106            return rulesBinder.forPattern( pattern );
107        }
108    
109        /**
110         * Return the wrapped {@link RulesBinder}.
111         *
112         * @return The wrapped {@link RulesBinder}
113         */
114        protected RulesBinder rulesBinder()
115        {
116            return rulesBinder;
117        }
118    
119    }