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 */
017package org.apache.juneau.bean.html5;
018
019import org.apache.juneau.marshall.xml.*;
020
021/**
022 * A re-serializable, {@link String}-backed raw-content wrapper that the XML and HTML serializers emit <b>verbatim</b>.
023 *
024 * <p>
025 * This is the reusable analogue of handing the serializer a one-shot {@link java.io.Reader}: the value is emitted
026 * without any XML entity escaping or <c>_x####_</c> whitespace encoding, and without a wrapping element &mdash; but
027 * because it is backed by a {@code String} it can be serialized any number of times.  This makes a bean carrying a
028 * {@code RawText} value survive a serialize&rarr;object&rarr;serialize cycle (for the serialize direction), unlike a
029 * consumed {@code Reader}.
030 *
031 * <p>
032 * Typical use is embedding pre-built script/style bodies into a {@link Script}/{@link Style} element:
033 *
034 * <h5 class='figure'>Example:</h5>
035 * <p class='bjava'>
036 *    <jc>// Browser-safe raw JSON sidecar ('&lt;' pre-escaped to \\u003c by the caller).</jc>
037 *    Script <jv>s</jv> = <jsm>script</jsm>(<js>"application/json"</js>).text(<jsm>rawText</jsm>(<jv>escapedJson</jv>));
038 * </p>
039 *
040 * <p>
041 * <b>Safety:</b> content is emitted verbatim.  Because Juneau parses via a StAX
042 * {@link javax.xml.stream.XMLStreamReader}, a value containing a raw <js>'&lt;'</js> (e.g. a literal
043 * <c>&lt;/script&gt;</c> sequence) or a bare <js>'&amp;'</js> is browser-correct on serialize but will NOT round-trip
044 * back through Juneau's parser.  Callers embedding markup-bearing content are responsible for escaping <js>'&lt;'</js>
045 * to the JS/CSS unicode escape <js>"\\u003c"</js> before wrapping.
046 *
047 * <h5 class='section'>See Also:</h5><ul>
048 *    <li class='jm'>{@link HtmlBuilder#rawText(String)}
049 *    <li class='jic'>{@link RawContent}
050 * </ul>
051 */
052public class RawText implements RawContent {
053
054   private final String text;
055
056   /**
057    * Constructor.
058    *
059    * @param text The raw, verbatim text content.  Can be <jk>null</jk> (nothing is emitted).
060    */
061   public RawText(String text) {
062      this.text = text;
063   }
064
065   @Override /* Overridden from RawContent */
066   public String toString() {
067      return text;
068   }
069}