View Javadoc

1   package org.apache.commons.digester3.binder;
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.util.HashMap;
23  import java.util.Map;
24  
25  import org.apache.commons.digester3.SetNestedPropertiesRule;
26  
27  /**
28   * Builder chained when invoking {@link LinkedRuleBuilder#setNestedProperties()}.
29   *
30   * @since 3.0
31   */
32  public final class NestedPropertiesBuilder
33      extends AbstractBackToLinkedRuleBuilder<SetNestedPropertiesRule>
34  {
35  
36      private final Map<String, String> elementNames = new HashMap<String, String>();
37  
38      private boolean trimData = true;
39  
40      private boolean allowUnknownChildElements = false;
41  
42      NestedPropertiesBuilder( String keyPattern, String namespaceURI, RulesBinder mainBinder,
43                                      LinkedRuleBuilder mainBuilder )
44      {
45          super( keyPattern, namespaceURI, mainBinder, mainBuilder );
46      }
47  
48      /**
49       * Allows ignore a matching element.
50       *
51       * @param elementName The child xml element to be ignored
52       * @return this builder instance
53       */
54      public NestedPropertiesBuilder ignoreElement( String elementName )
55      {
56          if ( elementName == null )
57          {
58              reportError( "setNestedProperties().ignoreElement( String )", "empty 'elementName' not allowed" );
59          }
60          return addAlias( elementName ).forProperty( null );
61      }
62  
63      /**
64       * Allows element2property mapping to be overridden.
65       *
66       * @param elementName The child xml element to match
67       * @param propertyName The java bean property to be assigned the value
68       * @return this builder instance
69       * @deprecated
70       */
71      @Deprecated
72      public NestedPropertiesBuilder addAlias( String elementName, String propertyName )
73      {
74          return addAlias( elementName ).forProperty( propertyName );
75      }
76  
77      /**
78       * Allows element2property mapping to be overridden.
79       *
80       * @param elementName The child xml element to match
81       * @return the property alias builder
82       * @since 3.2
83       */
84      public AddAliasBuilder<NestedPropertiesBuilder> addAlias( String elementName )
85      {
86          if ( elementName == null )
87          {
88              reportError( "setProperties().addAlias( String )", "empty 'elementName' not allowed" );
89          }
90          return new AddAliasBuilder<NestedPropertiesBuilder>( this, elementNames, elementName );
91      }
92  
93      /**
94       * When set to true, any text within child elements will have leading
95       * and trailing whitespace removed before assignment to the target
96       * object.
97       *
98       * @param trimData Flag to set any text within child elements will have leading
99       *                 and trailing whitespace removed
100      * @return this builder instance
101      */
102     public NestedPropertiesBuilder trimData( boolean trimData )
103     {
104         this.trimData = trimData;
105         return this;
106     }
107 
108     /**
109      * Determines whether an error is reported when a nested element is encountered for which there is no corresponding
110      * property-setter method.
111      *
112      * @param allowUnknownChildElements flag to ignore any child element for which there is no corresponding
113      *        object property
114      * @return this builder instance
115      */
116     public NestedPropertiesBuilder allowUnknownChildElements( boolean allowUnknownChildElements )
117     {
118         this.allowUnknownChildElements = allowUnknownChildElements;
119         return this;
120     }
121 
122     /**
123      * {@inheritDoc}
124      */
125     @Override
126     protected SetNestedPropertiesRule createRule()
127     {
128         SetNestedPropertiesRule rule = new SetNestedPropertiesRule( elementNames );
129         rule.setTrimData( trimData );
130         rule.setAllowUnknownChildElements( allowUnknownChildElements );
131         return rule;
132     }
133 
134 }