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.common.utils.StringUtils.*;
020import static org.apache.juneau.xml.annotation.XmlFormat.*;
021
022import java.net.*;
023
024import org.apache.juneau.annotation.*;
025import org.apache.juneau.xml.annotation.*;
026
027/**
028 * Identifies the software agent used to generate an Atom feed.
029 *
030 * <p>
031 * The generator element provides information about the software that created the feed. This is 
032 * useful for debugging, analytics, and understanding the tools used in feed creation.
033 *
034 * <p>
035 * The generator has three components:
036 * <ul class='spaced-list'>
037 *    <li><b>Text content</b> (required) - Human-readable name of the generating agent
038 *    <li><b>uri attribute</b> (optional) - URI identifying or describing the generating agent
039 *    <li><b>version attribute</b> (optional) - Version of the generating agent
040 * </ul>
041 *
042 * <h5 class='figure'>Schema</h5>
043 * <p class='bschema'>
044 *    atomGenerator = element atom:generator {
045 *       atomCommonAttributes,
046 *       attribute uri { atomUri }?,
047 *       attribute version { text }?,
048 *       text
049 *    }
050 * </p>
051 *
052 * <h5 class='section'>Example:</h5>
053 * <p class='bjava'>
054 *    Generator <jv>gen</jv> = <jk>new</jk> Generator(<js>"My Blog Software"</js>)
055 *       .setUri(<js>"http://www.myblogsoftware.com"</js>)
056 *       .setVersion(<js>"2.0"</js>);
057 *
058 *    Feed <jv>feed</jv> = <jk>new</jk> Feed(...)
059 *       .setGenerator(<jv>gen</jv>);
060 * </p>
061 *
062 * <h5 class='section'>Specification:</h5>
063 * <p>
064 * Represents an <c>atomGenerator</c> construct in the 
065 * <a class="doclink" href="https://tools.ietf.org/html/rfc4287#section-4.2.4">RFC 4287 - Section 4.2.4</a> specification.
066 *
067 * <h5 class='section'>See Also:</h5><ul>
068 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanAtom">juneau-bean-atom</a>
069 *    <li class='extlink'><a class="doclink" href="https://tools.ietf.org/html/rfc4287">RFC 4287 - The Atom Syndication Format</a>
070 * </ul>
071 */
072@Bean(typeName="generator")
073public class Generator extends Common {
074
075   private URI uri;
076   private String version;
077   private String text;
078
079
080   /**
081    * Normal constructor.
082    *
083    * @param text The generator statement content.
084    */
085   public Generator(String text) {
086      this.text = text;
087   }
088
089   /** Bean constructor. */
090   public Generator() {}
091
092
093   //-----------------------------------------------------------------------------------------------------------------
094   // Bean properties
095   //-----------------------------------------------------------------------------------------------------------------
096
097   /**
098    * Bean property getter:  <property>uri</property>.
099    *
100    * <p>
101    * The URI of this generator statement.
102    *
103    * @return The property value, or <jk>null</jk> if it is not set.
104    */
105   @Xml(format=ATTR)
106   public URI getUri() {
107      return uri;
108   }
109
110   /**
111    * Bean property setter:  <property>uri</property>.
112    *
113    * <p>
114    * The URI of this generator statement.
115    *
116    * <p>
117    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
118    * Strings must be valid URIs.
119    *
120    * @param value
121    *    The new value for this property.
122    *    <br>Can be <jk>null</jk> to unset the property.
123    * @return This object
124    */
125   public Generator setUri(Object value) {
126      this.uri = toURI(value);
127      return this;
128   }
129
130   /**
131    * Bean property getter:  <property>version</property>.
132    *
133    * <p>
134    * The version of this generator statement.
135    *
136    * @return The property value, or <jk>null</jk> if it is not set.
137    */
138   @Xml(format=ATTR)
139   public String getVersion() {
140      return version;
141   }
142
143   /**
144    * Bean property setter:  <property>version</property>.
145    *
146    * <p>
147    * The version of this generator statement.
148    *
149    * @param value
150    *    The new value for this property.
151    *    <br>Can be <jk>null</jk> to unset the property.
152    * @return This object
153    */
154   public Generator setVersion(String value) {
155      this.version = value;
156      return this;
157   }
158
159   /**
160    * Bean property getter:  <property>text</property>.
161    *
162    * <p>
163    * The content of this generator statement.
164    *
165    * @return The property value, or <jk>null</jk> if it is not set.
166    */
167   @Xml(format=TEXT)
168   public String getText() {
169      return text;
170   }
171
172   /**
173    * Bean property setter:  <property>text</property>.
174    *
175    * <p>
176    * The content of this generator statement.
177    *
178    * @param value
179    *    The new value for this property.
180    *    <br>Can be <jk>null</jk> to unset the property.
181    * @return This object
182    */
183   public Generator setText(String value) {
184      this.text = value;
185      return this;
186   }
187
188   //-----------------------------------------------------------------------------------------------------------------
189   // Overridden setters (to simplify method chaining)
190   //-----------------------------------------------------------------------------------------------------------------
191
192   @Override /* Overridden from Common */
193   public Generator setBase(Object value) {
194      super.setBase(value);
195      return this;
196   }
197
198   @Override /* Overridden from Common */
199   public Generator setLang(String value) {
200      super.setLang(value);
201      return this;
202   }
203}