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.xml.annotation.XmlFormat.*;
020
021import org.apache.juneau.xml.annotation.*;
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 */
091public class Text extends Common {
092
093   private String type;
094   private String text; // NOSONAR - Intentional naming.
095
096   /** Bean constructor. */
097   public Text() {}
098
099   /**
100    * Normal content.
101    *
102    * @param type The content type of this content.
103    */
104   public Text(String type) {
105      setType(type);
106   }
107
108   /**
109    * Bean property getter:  <property>text</property>.
110    *
111    * <p>
112    * The content of this content.
113    *
114    * @return The property value, or <jk>null</jk> if it is not set.
115    */
116   @Xml(format = XMLTEXT)
117   public String getText() { return text; }
118
119   /**
120    * Bean property getter:  <property>type</property>.
121    *
122    * <p>
123    * The content type of this content.
124    *
125    * @return The property value, or <jk>null</jk> if it is not set.
126    */
127   @Xml(format = ATTR)
128   public String getType() { return type; }
129
130   @Override /* Overridden from Common */
131   public Text setBase(Object value) {
132      super.setBase(value);
133      return this;
134   }
135
136   @Override /* Overridden from Common */
137   public Text setLang(String value) {
138      super.setLang(value);
139      return this;
140   }
141
142   /**
143    * Bean property setter:  <property>text</property>.
144    *
145    * <p>
146    * The content of this content.
147    *
148    * @param value
149    *    The new value for this property.
150    *    <br>Can be <jk>null</jk> to unset the property.
151    * @return This object
152    */
153   public Text setText(String value) {
154      text = value;
155      return this;
156   }
157
158   /**
159    * Bean property setter:  <property>type</property>.
160    *
161    * <p>
162    * The content type of this content.
163    *
164    * <p>
165    * Must be one of the following:
166    * <ul>
167    *    <li><js>"text"</js>
168    *    <li><js>"html"</js>
169    *    <li><js>"xhtml"</js>
170    *    <li><jk>null</jk> (defaults to <js>"text"</js>)
171    * </ul>
172    *
173    * @param value
174    *    The new value for this property.
175    *    <br>Can be <jk>null</jk> to unset the property.
176    * @return This object
177    */
178   public Text setType(String value) {
179      type = value;
180      return this;
181   }
182}