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.commons.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   /** Bean constructor. */
080   public Generator() {}
081
082   /**
083    * Normal constructor.
084    *
085    * @param text The generator statement content.
086    */
087   public Generator(String text) {
088      this.text = text;
089   }
090
091   /**
092    * Bean property getter:  <property>text</property>.
093    *
094    * <p>
095    * The content of this generator statement.
096    *
097    * @return The property value, or <jk>null</jk> if it is not set.
098    */
099   @Xml(format = TEXT)
100   public String getText() { return text; }
101
102   /**
103    * Bean property getter:  <property>uri</property>.
104    *
105    * <p>
106    * The URI of this generator statement.
107    *
108    * @return The property value, or <jk>null</jk> if it is not set.
109    */
110   @Xml(format = ATTR)
111   public URI getUri() { return uri; }
112
113   /**
114    * Bean property getter:  <property>version</property>.
115    *
116    * <p>
117    * The version of this generator statement.
118    *
119    * @return The property value, or <jk>null</jk> if it is not set.
120    */
121   @Xml(format = ATTR)
122   public String getVersion() { return version; }
123
124   @Override /* Overridden from Common */
125   public Generator setBase(Object value) {
126      super.setBase(value);
127      return this;
128   }
129
130   @Override /* Overridden from Common */
131   public Generator setLang(String value) {
132      super.setLang(value);
133      return this;
134   }
135
136   /**
137    * Bean property setter:  <property>text</property>.
138    *
139    * <p>
140    * The content of this generator statement.
141    *
142    * @param value
143    *    The new value for this property.
144    *    <br>Can be <jk>null</jk> to unset the property.
145    * @return This object
146    */
147   public Generator setText(String value) {
148      text = value;
149      return this;
150   }
151
152   /**
153    * Bean property setter:  <property>uri</property>.
154    *
155    * <p>
156    * The URI of this generator statement.
157    *
158    * <p>
159    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
160    * Strings must be valid URIs.
161    *
162    * @param value
163    *    The new value for this property.
164    *    <br>Can be <jk>null</jk> to unset the property.
165    * @return This object
166    */
167   public Generator setUri(Object value) {
168      this.uri = toUri(value);
169      return this;
170   }
171
172   /**
173    * Bean property setter:  <property>version</property>.
174    *
175    * <p>
176    * The version 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 setVersion(String value) {
184      version = value;
185      return this;
186   }
187}