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.*;
020
021import java.net.*;
022
023/**
024 * Represents a person, corporation, or similar entity in an Atom document.
025 *
026 * <p>
027 * Person constructs are used to describe authors, contributors, and other people or entities 
028 * associated with a feed or entry. Each person construct contains a name and optionally a URI 
029 * and email address.
030 *
031 * <p>
032 * Person constructs appear in several places:
033 * <ul class='spaced-list'>
034 *    <li><c>atom:author</c> - Indicates the author(s) of a feed or entry
035 *    <li><c>atom:contributor</c> - Indicates those who contributed to a feed or entry
036 * </ul>
037 *
038 * <h5 class='figure'>Schema</h5>
039 * <p class='bschema'>
040 *    atomPersonConstruct =
041 *       atomCommonAttributes,
042 *       (element atom:name { text }
043 *       &amp; element atom:uri { atomUri }?
044 *       &amp; element atom:email { atomEmailAddress }?
045 *       &amp; extensionElement*)
046 * </p>
047 *
048 * <h5 class='section'>Example:</h5>
049 * <p class='bjava'>
050 *    <jc>// Create an author</jc>
051 *    Person <jv>author</jv> = <jk>new</jk> Person(<js>"Jane Doe"</js>)
052 *       .setEmail(<js>"jane@example.org"</js>)
053 *       .setUri(<js>"http://example.org/~jane"</js>);
054 *
055 *    <jc>// Add to entry</jc>
056 *    Entry <jv>entry</jv> = <jk>new</jk> Entry(...)
057 *       .setAuthors(<jv>author</jv>);
058 * </p>
059 *
060 * <h5 class='section'>Specification:</h5>
061 * <p>
062 * Represents an <c>atomPersonConstruct</c> in the 
063 * <a class="doclink" href="https://tools.ietf.org/html/rfc4287#section-3.2">RFC 4287 - Section 3.2</a> specification.
064 *
065 * <h5 class='section'>See Also:</h5><ul>
066 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanAtom">juneau-bean-atom</a>
067 *    <li class='extlink'><a class="doclink" href="https://tools.ietf.org/html/rfc4287">RFC 4287 - The Atom Syndication Format</a>
068 * </ul>
069 */
070public class Person extends Common {
071
072   private String name;
073   private URI uri;
074   private String email;
075
076
077   /**
078    * Normal constructor.
079    *
080    * @param name The name of the person.
081    */
082   public Person(String name) {
083      setName(name);
084   }
085
086   /** Bean constructor. */
087   public Person() {}
088
089
090   //-----------------------------------------------------------------------------------------------------------------
091   // Bean properties
092   //-----------------------------------------------------------------------------------------------------------------
093
094   /**
095    * Bean property getter:  <property>name</property>.
096    *
097    * <p>
098    * Returns the human-readable name for the person (required).
099    *
100    * @return The property value, or <jk>null</jk> if it is not set.
101    */
102   public String getName() {
103      return name;
104   }
105
106   /**
107    * Bean property setter:  <property>name</property>.
108    *
109    * <p>
110    * Sets the human-readable name for the person (required).
111    *
112    * <h5 class='section'>Example:</h5>
113    * <p class='bjava'>
114    *    Person <jv>person</jv> = <jk>new</jk> Person(<js>"Jane Doe"</js>);
115    * </p>
116    *
117    * @param value
118    *    The new value for this property.
119    *    <br>Can be <jk>null</jk> to unset the property.
120    * @return This object.
121    */
122   public Person setName(String value) {
123      this.name = value;
124      return this;
125   }
126
127   /**
128    * Bean property getter:  <property>uri</property>.
129    *
130    * <p>
131    * Returns a URI associated with the person.
132    *
133    * <p>
134    * Typically this is a personal website or profile page.
135    *
136    * @return The property value, or <jk>null</jk> if it is not set.
137    */
138   public URI getUri() {
139      return uri;
140   }
141
142   /**
143    * Bean property setter:  <property>uri</property>.
144    *
145    * <p>
146    * Sets a URI associated with the person (typically a website or profile page).
147    *
148    * <p>
149    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
150    * Strings must be valid URIs.
151    *
152    * <h5 class='section'>Example:</h5>
153    * <p class='bjava'>
154    *    Person <jv>person</jv> = <jk>new</jk> Person(<js>"Jane Doe"</js>)
155    *       .setUri(<js>"http://example.org/~jane"</js>);
156    * </p>
157    *
158    * @param value
159    *    The new value for this property.
160    *    <br>Can be <jk>null</jk> to unset the property.
161    * @return This object.
162    */
163   public Person setUri(Object value) {
164      this.uri = toURI(value);
165      return this;
166   }
167
168   /**
169    * Bean property getter:  <property>email</property>.
170    *
171    * <p>
172    * Returns the email address associated with the person.
173    *
174    * @return The property value, or <jk>null</jk> if it is not set.
175    */
176   public String getEmail() {
177      return email;
178   }
179
180   /**
181    * Bean property setter:  <property>email</property>.
182    *
183    * <p>
184    * Sets the email address associated with the person.
185    *
186    * <h5 class='section'>Example:</h5>
187    * <p class='bjava'>
188    *    Person <jv>person</jv> = <jk>new</jk> Person(<js>"Jane Doe"</js>)
189    *       .setEmail(<js>"jane@example.org"</js>);
190    * </p>
191    *
192    * @param value
193    *    The new value for this property.
194    *    <br>Can be <jk>null</jk> to unset the property.
195    * @return This object.
196    */
197   public Person setEmail(String value) {
198      this.email = value;
199      return this;
200   }
201
202   //-----------------------------------------------------------------------------------------------------------------
203   // Overridden setters (to simplify method chaining)
204   //-----------------------------------------------------------------------------------------------------------------
205
206   @Override /* Overridden from Common */
207   public Person setBase(Object value) {
208      super.setBase(value);
209      return this;
210   }
211
212   @Override /* Overridden from Common */
213   public Person setLang(String value) {
214      super.setLang(value);
215      return this;
216   }
217}