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.marshall.xml;
018
019/**
020 * Marker interface for objects whose {@link #toString()} value should be emitted <b>verbatim</b> as raw element
021 * content by the XML and HTML serializers.
022 *
023 * <p>
024 * This is the re-serializable analogue of the raw {@link java.io.Reader}/{@link java.io.InputStream} path: the value is
025 * appended as-is (no XML entity escaping, no <c>_x####_</c> whitespace/invalid-char encoding, no wrapping element), but
026 * because it is backed by a reusable value (typically a {@code String}) it survives repeated serialization &mdash;
027 * unlike a one-shot {@code Reader} which is consumed on first use.
028 *
029 * <p>
030 * Implementations are responsible for producing content that is safe for the target syntax.  Notably, because Juneau
031 * parses via a StAX {@link javax.xml.stream.XMLStreamReader}, content containing a raw <js>'&lt;'</js> or a bare
032 * <js>'&amp;'</js> will serialize correctly (browser-safe) but will NOT round-trip back through Juneau's parser.
033 *
034 * <h5 class='section'>See Also:</h5><ul>
035 *    <li class='jf'>{@link XmlFormat#RAWTEXT}
036 * </ul>
037 */
038public interface RawContent {
039
040   /**
041    * Returns the raw, verbatim character content to emit.
042    *
043    * @return The raw content.  May be <jk>null</jk> (nothing is emitted).
044    */
045   @Override
046   String toString();
047}