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