View Javadoc

1   package org.apache.commons.digester3.annotations.rules;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with 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,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.lang.annotation.Documented;
23  import java.lang.annotation.ElementType;
24  import java.lang.annotation.Retention;
25  import java.lang.annotation.RetentionPolicy;
26  import java.lang.annotation.Target;
27  
28  import org.apache.commons.digester3.AbstractObjectCreationFactory;
29  import org.apache.commons.digester3.FactoryCreateRule;
30  import org.apache.commons.digester3.annotations.DigesterRule;
31  import org.apache.commons.digester3.annotations.DigesterRuleList;
32  import org.apache.commons.digester3.annotations.handlers.FactoryCreateHandler;
33  import org.xml.sax.Attributes;
34  
35  /**
36   * Classes annotated with {@code FactoryCreate} will be bound with {@code FactoryCreateRule} digester rule.
37   * 
38   * @see org.apache.commons.digester3.Digester#addFactoryCreate(String,org.apache.commons.digester3.ObjectCreationFactory,boolean)
39   * @since 2.1
40   */
41  @Documented
42  @Retention( RetentionPolicy.RUNTIME )
43  @Target( ElementType.TYPE )
44  @CreationRule
45  @DigesterRule( reflectsRule = FactoryCreateRule.class, handledBy = FactoryCreateHandler.class )
46  public @interface FactoryCreate
47  {
48  
49      /**
50       * The Java class of the object creation factory class.
51       */
52      Class<? extends AbstractObjectCreationFactory<?>> factoryClass() default DefaultObjectCreationFactory.class;
53  
54      /**
55       * Allows specify the attribute containing an override class name if it is present.
56       *
57       * @since 3.0
58       */
59      String attributeName() default "";
60  
61      /**
62       * The element matching pattern.
63       */
64      String pattern();
65  
66      /**
67       * The namespace URI for which this Rule is relevant, if any.
68       *
69       * @since 3.0
70       */
71      String namespaceURI() default "";
72  
73      /**
74       * When true any exceptions thrown during object creation will be ignored.
75       */
76      boolean ignoreCreateExceptions() default false;
77  
78      /**
79       * Defines several {@code @FactoryCreate} annotations on the same element.
80       * 
81       * @see FactoryCreate
82       */
83      @Documented
84      @Retention( RetentionPolicy.RUNTIME )
85      @Target( ElementType.TYPE )
86      @DigesterRuleList
87      @interface List
88      {
89          FactoryCreate[] value();
90      }
91  
92      /**
93       * Dummy ObjectCreationFactory type - only for annotation value type purposes.
94       */
95      public static final class DefaultObjectCreationFactory
96          extends AbstractObjectCreationFactory<Object>
97      {
98  
99          /**
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 }