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   /** Bean constructor. */
085   public Id() {}
086
087   /**
088    * Normal constructor.
089    *
090    * @param text The id element contents.
091    */
092   public Id(String text) {
093      setText(text);
094   }
095
096   /**
097    * Bean property getter:  <property>text</property>.
098    *
099    * <p>
100    * The content of this identifier.
101    *
102    * @return The property value, or <jk>null</jk> if it is not set.
103    */
104   @Xml(format = TEXT)
105   public String getText() { return text; }
106
107   @Override /* Overridden from Common */
108   public Id setBase(Object value) {
109      super.setBase(value);
110      return this;
111   }
112
113   @Override /* Overridden from Common */
114   public Id setLang(String value) {
115      super.setLang(value);
116      return this;
117   }
118
119   /**
120    * Bean property setter:  <property>text</property>.
121    *
122    * <p>
123    * The content of this identifier.
124    *
125    * @param value
126    *    The new value for this property.
127    *    <br>Can be <jk>null</jk> to unset the property.
128    * @return This object
129    */
130   public Id setText(String value) {
131      text = value;
132      return this;
133   }
134}