001    package org.apache.commons.digester3.annotations.rules;
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    import java.lang.annotation.Documented;
023    import java.lang.annotation.ElementType;
024    import java.lang.annotation.Retention;
025    import java.lang.annotation.RetentionPolicy;
026    import java.lang.annotation.Target;
027    
028    import org.apache.commons.digester3.AbstractObjectCreationFactory;
029    import org.apache.commons.digester3.FactoryCreateRule;
030    import org.apache.commons.digester3.annotations.DigesterRule;
031    import org.apache.commons.digester3.annotations.DigesterRuleList;
032    import org.apache.commons.digester3.annotations.handlers.FactoryCreateHandler;
033    import org.xml.sax.Attributes;
034    
035    /**
036     * Classes annotated with {@code FactoryCreate} will be bound with {@code FactoryCreateRule} digester rule.
037     * 
038     * @see org.apache.commons.digester3.Digester#addFactoryCreate(String,org.apache.commons.digester3.ObjectCreationFactory,boolean)
039     * @since 2.1
040     */
041    @Documented
042    @Retention( RetentionPolicy.RUNTIME )
043    @Target( ElementType.TYPE )
044    @CreationRule
045    @DigesterRule( reflectsRule = FactoryCreateRule.class, handledBy = FactoryCreateHandler.class )
046    public @interface FactoryCreate
047    {
048    
049        /**
050         * The Java class of the object creation factory class.
051         */
052        Class<? extends AbstractObjectCreationFactory<?>> factoryClass() default DefaultObjectCreationFactory.class;
053    
054        /**
055         * Allows specify the attribute containing an override class name if it is present.
056         *
057         * @since 3.0
058         */
059        String attributeName() default "";
060    
061        /**
062         * The element matching pattern.
063         */
064        String pattern();
065    
066        /**
067         * The namespace URI for which this Rule is relevant, if any.
068         *
069         * @since 3.0
070         */
071        String namespaceURI() default "";
072    
073        /**
074         * When true any exceptions thrown during object creation will be ignored.
075         */
076        boolean ignoreCreateExceptions() default false;
077    
078        /**
079         * Defines several {@code @FactoryCreate} annotations on the same element.
080         * 
081         * @see FactoryCreate
082         */
083        @Documented
084        @Retention( RetentionPolicy.RUNTIME )
085        @Target( ElementType.TYPE )
086        @DigesterRuleList
087        @interface List
088        {
089            FactoryCreate[] value();
090        }
091    
092        /**
093         * Dummy ObjectCreationFactory type - only for annotation value type purposes.
094         */
095        public static final class DefaultObjectCreationFactory
096            extends AbstractObjectCreationFactory<Object>
097        {
098    
099            /**
100             * {@inheritDoc}
101             */
102            @Override
103            public Object createObject( Attributes attributes )
104                throws Exception
105            {
106                // do nothing
107                return null;
108            }
109    
110        }
111    
112    }