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    }