View Javadoc

1   /*
2    * Copyright 2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.commons.betwixt.strategy;
18  
19  import org.apache.commons.betwixt.ElementDescriptor;
20  
21  /***
22   * <p>Encodes body content.
23   * </p><p>
24   * <strong>Usage:</strong> 
25   * Used by {@link BeanWriter} to encode body content before it is written
26   * into the textual output.
27   * This gives flexibility in this stage allowing (for example)
28   * some properties to use character escaping whilst others 
29   * use <code>CDATA</code> wrapping.
30   * </p>
31   * <p><strong>Note:</strong> the word <code>encoding</code> here is used 
32   * in the sense of escaping a sequence of character data.
33   * </p>
34   * @author <a href='http://jakarta.apache.org/'>Jakarta Commons Team</a>
35   * @since 0.5
36   */
37  public abstract class MixedContentEncodingStrategy {
38  
39      /*** 
40       * The name of the option used to specify encoding on a per-element
41       * basis is
42       * <code>org.apache.commons.betwixt.mixed-content-encoding</code> 
43       */
44      public static final String ENCODING_OPTION_NAME 
45          = "org.apache.commons.betwixt.mixed-content-encoding";
46      /*** The option value for CDATA */
47      public static final String CDATA_ENCODING = "CDATA";
48  
49      /***
50       * The standard implementation used by Betwixt by default.
51       * The default is to escape as character data unless
52       * the <code>ElementDescriptor</code> contains
53       * an option with name 
54       * <code>org.apache.commons.betwixt.mixed-content-encoding</code>
55       * and value <code>CDATA</code>.
56       * This is a singleton.
57       */
58      public static final MixedContentEncodingStrategy DEFAULT 
59              = new BaseMixedContentEncodingStrategy() {
60          /***
61           * Encode by escaping character data unless
62           * the <code>ElementDescriptor</code> contains
63           * an option with name 
64           * <code>org.apache.commons.betwixt.mixed-content-encoding</code>
65           * and value <code>CDATA</code>.
66           */
67          protected boolean encodeAsCDATA(ElementDescriptor element) {
68              boolean result = false;
69              if (element != null ) {
70                  String optionValue = element.getOptions().getValue(ENCODING_OPTION_NAME);
71                  result = CDATA_ENCODING.equals(optionValue);        
72              }
73              return result;       
74          }
75      };
76      
77      /***
78       * Encodes element content within a <code>CDATA</code> section.
79       * This is a singleton.
80       */
81      public static final MixedContentEncodingStrategy CDATA 
82              = new BaseMixedContentEncodingStrategy() {
83          /***
84           * Always encode by escaping character data.
85           */
86          protected boolean encodeAsCDATA(ElementDescriptor element) {
87              return true;       
88          }
89      };    
90  
91      /***
92        * Encodes by escaping character data.
93        * This is a singleton.
94        */
95       public static final MixedContentEncodingStrategy ESCAPED_CHARACTERS 
96               = new BaseMixedContentEncodingStrategy() {
97           /***
98            * Always encode by escaping character data.
99            */
100          protected boolean encodeAsCDATA(ElementDescriptor element) {
101              return false;       
102          }
103      };
104     
105 
106     /***
107      * Encodes the body content into a form suitable for output as 
108      * (textual) xml.
109      * @param bodyContent the raw (unescaped) character data, not null
110      * @param element the <code>ElementDescriptor</code> describing the element
111      * whose content is being encoded.
112      * @return the encoded (escaped) character data, not null
113      */
114     public abstract String encode(String bodyContent, ElementDescriptor element);
115 }