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.atom;
018
019import static org.apache.juneau.marshall.xml.XmlFormat.*;
020
021import org.apache.juneau.marshall.xml.*;
022
023/**
024 * Represents human-readable text in an Atom document.
025 *
026 * <p>
027 * Text constructs are used throughout Atom for elements that contain human-readable text
028 * such as titles, summaries, rights statements, and subtitles. They support three content types:
029 *
030 * <ul class='spaced-list'>
031 *    <li><c>"text"</c> - Plain text with no markup (default)
032 *    <li><c>"html"</c> - HTML markup, entity-escaped
033 *    <li><c>"xhtml"</c> - Well-formed XHTML in a div container
034 * </ul>
035 *
036 * <p>
037 * Text constructs are the base class for {@link Content} and are used directly for:
038 * <ul class='spaced-list'>
039 *    <li><c>atom:title</c> - Entry and feed titles
040 *    <li><c>atom:subtitle</c> - Feed subtitles
041 *    <li><c>atom:summary</c> - Entry summaries
042 *    <li><c>atom:rights</c> - Copyright and rights statements
043 * </ul>
044 *
045 * <h5 class='figure'>Schema</h5>
046 * <p class='bschema'>
047 *    atomTextConstruct = atomPlainTextConstruct | atomXHTMLTextConstruct
048 *
049 *    atomPlainTextConstruct =
050 *       atomCommonAttributes,
051 *       attribute type { "text" | "html" }?,
052 *       text
053 *
054 *    atomXHTMLTextConstruct =
055 *       atomCommonAttributes,
056 *       attribute type { "xhtml" },
057 *       xhtmlDiv
058 *
059 *    xhtmlDiv = element xhtml:div {
060 *       (attribute * { text }
061 *       | text
062 *       | anyXHTML)*
063 *    }
064 * </p>
065 *
066 * <h5 class='section'>Examples:</h5>
067 * <p class='bjava'>
068 *    <jc>// Plain text</jc>
069 *    Text <jv>t1</jv> = <jk>new</jk> Text(<js>"text"</js>)
070 *       .setText(<js>"Plain text title"</js>);
071 *
072 *    <jc>// HTML (entity-escaped)</jc>
073 *    Text <jv>t2</jv> = <jk>new</jk> Text(<js>"html"</js>)
074 *       .setText(<js>"Title with &lt;em&gt;emphasis&lt;/em&gt;"</js>);
075 *
076 *    <jc>// XHTML</jc>
077 *    Text <jv>t3</jv> = <jk>new</jk> Text(<js>"xhtml"</js>)
078 *       .setText(<js>"&lt;div xmlns='http://www.w3.org/1999/xhtml'&gt;&lt;p&gt;XHTML title&lt;/p&gt;&lt;/div&gt;"</js>);
079 * </p>
080 *
081 * <h5 class='section'>Specification:</h5>
082 * <p>
083 * Represents an <c>atomTextConstruct</c> in the
084 * <a class="doclink" href="https://tools.ietf.org/html/rfc4287#section-3.1">RFC 4287 - Section 3.1</a> specification.
085 *
086 * <h5 class='section'>See Also:</h5><ul>
087 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanAtom">juneau-bean-atom</a>
088 *    <li class='extlink'><a class="doclink" href="https://tools.ietf.org/html/rfc4287">RFC 4287 - The Atom Syndication Format</a>
089 * </ul>
090 */
091@SuppressWarnings({
092   "java:S1700" // Field name intentionally matches class name
093})
094public class Text extends Common {
095
096   private String type;
097   private String text;
098
099   /** Bean constructor. */
100   public Text() {}
101
102   /**
103    * Normal content.
104    *
105    * @param type The content type of this content.  Can be <jk>null</jk> to leave the property unset.
106    */
107   public Text(String type) {
108      setType(type);
109   }
110
111   /**
112    * Bean property getter:  <property>text</property>.
113    *
114    * <p>
115    * The content of this content.
116    *
117    * @return The property value, or <jk>null</jk> if it is not set.
118    */
119   @Xml(format = XMLTEXT)
120   public String getText() { return text; }
121
122   /**
123    * Bean property getter:  <property>type</property>.
124    *
125    * <p>
126    * The content type of this content.
127    *
128    * @return The property value, or <jk>null</jk> if it is not set.
129    */
130   @Xml(format = ATTR)
131   public String getType() { return type; }
132
133   @Override /* Overridden from Common */
134   public Text setBase(Object value) {
135      super.setBase(value);
136      return this;
137   }
138
139   @Override /* Overridden from Common */
140   public Text setLang(String value) {
141      super.setLang(value);
142      return this;
143   }
144
145   /**
146    * Bean property setter:  <property>text</property>.
147    *
148    * <p>
149    * The content of this content.
150    *
151    * @param value
152    *    The new value for this property.
153    *    <br>Can be <jk>null</jk> to unset the property.
154    * @return This object
155    */
156   public Text setText(String value) {
157      text = value;
158      return this;
159   }
160
161   /**
162    * Bean property setter:  <property>type</property>.
163    *
164    * <p>
165    * The content type of this content.
166    *
167    * <p>
168    * Must be one of the following:
169    * <ul>
170    *    <li><js>"text"</js>
171    *    <li><js>"html"</js>
172    *    <li><js>"xhtml"</js>
173    *    <li><jk>null</jk> (defaults to <js>"text"</js>)
174    * </ul>
175    *
176    * @param value
177    *    The new value for this property.
178    *    <br>Can be <jk>null</jk> to unset the property.
179    * @return This object
180    */
181   public Text setType(String value) {
182      type = value;
183      return this;
184   }
185}