001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.betwixt.strategy;
019
020 import org.apache.commons.betwixt.ElementDescriptor;
021
022 /**
023 * <p>Encodes body content.
024 * </p><p>
025 * <strong>Usage:</strong>
026 * Used by {@link org.apache.commons.betwixt.io.BeanWriter} to encode body content before it is written
027 * into the textual output.
028 * This gives flexibility in this stage allowing (for example)
029 * some properties to use character escaping whilst others
030 * use <code>CDATA</code> wrapping.
031 * </p>
032 * <p><strong>Note:</strong> the word <code>encoding</code> here is used
033 * in the sense of escaping a sequence of character data.
034 * </p>
035 * @author <a href='http://commons.apache.org/'>Apache Commons Team</a>
036 * @since 0.5
037 */
038 public abstract class MixedContentEncodingStrategy {
039
040 /**
041 * The name of the option used to specify encoding on a per-element
042 * basis is
043 * <code>org.apache.commons.betwixt.mixed-content-encoding</code>
044 */
045 public static final String ENCODING_OPTION_NAME
046 = "org.apache.commons.betwixt.mixed-content-encoding";
047 /** The option value for CDATA */
048 public static final String CDATA_ENCODING = "CDATA";
049
050 /**
051 * The standard implementation used by Betwixt by default.
052 * The default is to escape as character data unless
053 * the <code>ElementDescriptor</code> contains
054 * an option with name
055 * <code>org.apache.commons.betwixt.mixed-content-encoding</code>
056 * and value <code>CDATA</code>.
057 * This is a singleton.
058 */
059 public static final MixedContentEncodingStrategy DEFAULT
060 = new BaseMixedContentEncodingStrategy() {
061 /**
062 * Encode by escaping character data unless
063 * the <code>ElementDescriptor</code> contains
064 * an option with name
065 * <code>org.apache.commons.betwixt.mixed-content-encoding</code>
066 * and value <code>CDATA</code>.
067 */
068 protected boolean encodeAsCDATA(ElementDescriptor element) {
069 boolean result = false;
070 if (element != null ) {
071 String optionValue = element.getOptions().getValue(ENCODING_OPTION_NAME);
072 result = CDATA_ENCODING.equals(optionValue);
073 }
074 return result;
075 }
076 };
077
078 /**
079 * Encodes element content within a <code>CDATA</code> section.
080 * This is a singleton.
081 */
082 public static final MixedContentEncodingStrategy CDATA
083 = new BaseMixedContentEncodingStrategy() {
084 /**
085 * Always encode by escaping character data.
086 */
087 protected boolean encodeAsCDATA(ElementDescriptor element) {
088 return true;
089 }
090 };
091
092 /**
093 * Encodes by escaping character data.
094 * This is a singleton.
095 */
096 public static final MixedContentEncodingStrategy ESCAPED_CHARACTERS
097 = new BaseMixedContentEncodingStrategy() {
098 /**
099 * 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 }