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.marshall.xml.XmlFormat.*;
021
022import java.net.*;
023
024import org.apache.juneau.marshall.xml.*;
025
026/**
027 * Base class for all Atom elements, providing common attributes.
028 *
029 * <p>
030 * This abstract class defines attributes that can appear on any Atom element. Per RFC 4287,
031 * all Atom elements may have <c>xml:base</c> and <c>xml:lang</c> attributes for managing
032 * URIs and language context.
033 *
034 * <p>
035 * Common attributes:
036 * <ul class='spaced-list'>
037 *    <li><b>xml:base</b> - Establishes a base URI for resolving relative references
038 *    <li><b>xml:lang</b> - Indicates the natural language of the element's content
039 * </ul>
040 *
041 * <p>
042 * This class is extended by all Atom bean classes ({@link Feed}, {@link Entry}, {@link Link},
043 * {@link Person}, {@link Category}, {@link Text}, etc.).
044 *
045 * <h5 class='figure'>Schema</h5>
046 * <p class='bschema'>
047 *    atomCommonAttributes =
048 *       attribute xml:base { atomUri }?,
049 *       attribute xml:lang { atomLanguageTag }?,
050 *       undefinedAttribute*
051 * </p>
052 *
053 * <h5 class='section'>Examples:</h5>
054 * <p class='bjava'>
055 *    <jc>// Set base URI for relative link resolution</jc>
056 *    Feed <jv>feed</jv> = <jk>new</jk> Feed(...)
057 *       .setBase(<js>"http://example.org/"</js>);
058 *
059 *    <jc>// Set language</jc>
060 *    Text <jv>title</jv> = <jk>new</jk> Text(<js>"text"</js>)
061 *       .setText(<js>"My Feed"</js>)
062 *       .setLang(<js>"en"</js>);
063 * </p>
064 *
065 * <h5 class='section'>Specification:</h5>
066 * <p>
067 * Represents <c>atomCommonAttributes</c> in the
068 * <a class="doclink" href="https://tools.ietf.org/html/rfc4287#section-2">RFC 4287 - Section 2</a> specification.
069 *
070 * <h5 class='section'>See Also:</h5><ul>
071 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanAtom">juneau-bean-atom</a>
072 *    <li class='extlink'><a class="doclink" href="https://tools.ietf.org/html/rfc4287">RFC 4287 - The Atom Syndication Format</a>
073 * </ul>
074 */
075public abstract class Common {
076
077   private URI base;
078   private String lang;
079
080   /**
081    * Bean property getter:  <property>base</property>.
082    *
083    * <p>
084    * Returns the base URI for resolving relative URI references (xml:base attribute).
085    *
086    * <p>
087    * This attribute, defined by XML Base, establishes a base URI for resolving any
088    * relative references within the scope of this element. This is particularly useful
089    * when aggregating content from multiple sources.
090    *
091    * @return The property value, or <jk>null</jk> if it is not set.
092    */
093   @Xml(prefix = "xml", format = ATTR)
094   public URI getBase() { return base; }
095
096   /**
097    * Bean property getter:  <property>lang</property>.
098    *
099    * <p>
100    * Returns the natural language of the element's content (xml:lang attribute).
101    *
102    * <p>
103    * The language tag should be a language identifier as defined by RFC 3066. This attribute
104    * is inherited by child elements, so it need only be specified on the highest-level
105    * element where it applies.
106    *
107    * @return The property value, or <jk>null</jk> if it is not set.
108    */
109   @Xml(prefix = "xml", format = ATTR)
110   public String getLang() { return lang; }
111
112   /**
113    * Bean property setter:  <property>base</property>.
114    *
115    * <p>
116    * Sets the base URI for resolving relative URI references (xml:base attribute).
117    *
118    * <p>
119    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
120    * Strings must be valid URIs.
121    *
122    * <h5 class='section'>Example:</h5>
123    * <p class='bjava'>
124    *    Feed <jv>feed</jv> = <jk>new</jk> Feed(...)
125    *       .setBase(<js>"http://example.org/"</js>);
126    * </p>
127    *
128    * @param value
129    *    The new value for this property.
130    *    <br>Can be <jk>null</jk> to unset the property.
131    * @return This object.
132    */
133   public Common setBase(Object value) {
134      this.base = toUri(value);
135      return this;
136   }
137
138   /**
139    * Bean property setter:  <property>lang</property>.
140    *
141    * <p>
142    * Sets the natural language of the element's content (xml:lang attribute).
143    *
144    * <h5 class='section'>Example:</h5>
145    * <p class='bjava'>
146    *    Text <jv>title</jv> = <jk>new</jk> Text(<js>"text"</js>)
147    *       .setText(<js>"Mon Blog"</js>)
148    *       .setLang(<js>"fr"</js>);
149    * </p>
150    *
151    * @param value
152    *    The new value for this property (e.g., "en", "fr", "de", "en-US").
153    *    <br>Can be <jk>null</jk> to unset the property.
154    * @return This object.
155    */
156   public Common setLang(String value) {
157      lang = value;
158      return this;
159   }
160
161   @Override /* Overridden from Object */
162   public String toString() {
163      return XmlSerializer.DEFAULT_SQ.toString(this);
164   }
165}