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.annotation.*;
022import org.apache.juneau.xml.annotation.*;
023
024/**
025 * Represents a permanent, universally unique identifier for a feed or entry.
026 *
027 * <p>
028 * The ID element provides a permanent, globally unique identifier for feeds and entries. 
029 * IDs must never change, even if the resource is moved or its content is modified.
030 *
031 * <p>
032 * Requirements for IDs per RFC 4287:
033 * <ul class='spaced-list'>
034 *    <li>Must be a valid IRI (Internationalized Resource Identifier)
035 *    <li>Must be permanent - never changes
036 *    <li>Must be unique - no two feeds or entries should share the same ID
037 *    <li>Should be dereferenceable when possible (but not required)
038 * </ul>
039 *
040 * <p>
041 * Common ID formats:
042 * <ul class='spaced-list'>
043 *    <li><b>Tag URI</b> - <c>tag:example.org,2024:entry-123</c>
044 *    <li><b>HTTP URL</b> - <c>http://example.org/posts/123</c>
045 *    <li><b>UUID URN</b> - <c>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</c>
046 * </ul>
047 *
048 * <h5 class='figure'>Schema</h5>
049 * <p class='bschema'>
050 *    atomId = element atom:id {
051 *       atomCommonAttributes,
052 *       (atomUri)
053 *    }
054 * </p>
055 *
056 * <h5 class='section'>Examples:</h5>
057 * <p class='bjava'>
058 *    <jc>// Tag URI (recommended)</jc>
059 *    Id <jv>id1</jv> = <jk>new</jk> Id(<js>"tag:example.org,2024:feed"</js>);
060 *
061 *    <jc>// HTTP URL</jc>
062 *    Id <jv>id2</jv> = <jk>new</jk> Id(<js>"http://example.org/posts/123"</js>);
063 *
064 *    <jc>// UUID URN</jc>
065 *    Id <jv>id3</jv> = <jk>new</jk> Id(<js>"urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a"</js>);
066 * </p>
067 *
068 * <h5 class='section'>Specification:</h5>
069 * <p>
070 * Represents an <c>atomId</c> construct in the 
071 * <a class="doclink" href="https://tools.ietf.org/html/rfc4287#section-4.2.6">RFC 4287 - Section 4.2.6</a> specification.
072 *
073 * <h5 class='section'>See Also:</h5><ul>
074 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanAtom">juneau-bean-atom</a>
075 *    <li class='extlink'><a class="doclink" href="https://tools.ietf.org/html/rfc4287">RFC 4287 - The Atom Syndication Format</a>
076 *    <li class='extlink'><a class="doclink" href="https://www.ietf.org/rfc/rfc4151.txt">RFC 4151 - Tag URI Scheme</a>
077 * </ul>
078 */
079@Bean(typeName="id")
080public class Id extends Common {
081
082   private String text;
083
084   /**
085    * Normal constructor.
086    *
087    * @param text The id element contents.
088    */
089   public Id(String text) {
090      setText(text);
091   }
092
093   /** Bean constructor. */
094   public Id() {}
095
096
097   //-----------------------------------------------------------------------------------------------------------------
098   // Bean properties
099   //-----------------------------------------------------------------------------------------------------------------
100
101   /**
102    * Bean property getter:  <property>text</property>.
103    *
104    * <p>
105    * The content of this identifier.
106    *
107    * @return The property value, or <jk>null</jk> if it is not set.
108    */
109   @Xml(format=TEXT)
110   public String getText() {
111      return text;
112   }
113
114   /**
115    * Bean property setter:  <property>text</property>.
116    *
117    * <p>
118    * The content of this identifier.
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 Id setText(String value) {
126      this.text = value;
127      return this;
128   }
129
130   //-----------------------------------------------------------------------------------------------------------------
131   // Overridden setters (to simplify method chaining)
132   //-----------------------------------------------------------------------------------------------------------------
133
134   @Override /* Overridden from Common */
135   public Id setBase(Object value) {
136      super.setBase(value);
137      return this;
138   }
139
140   @Override /* Overridden from Common */
141   public Id setLang(String value) {
142      super.setLang(value);
143      return this;
144   }
145}