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.*;
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 * Represents a category or tag associated with a feed or entry.
029 *
030 * <p>
031 * Categories provide a way to classify or tag feeds and entries, enabling better organization 
032 * and discovery of content. Each category has a term (required) and optionally a scheme (for 
033 * namespacing) and a human-readable label.
034 *
035 * <p>
036 * Categories are commonly used for:
037 * <ul class='spaced-list'>
038 *    <li>Tagging entries by topic (e.g., "technology", "sports")
039 *    <li>Classifying content by category schemes (e.g., subject taxonomies)
040 *    <li>Enabling feed filtering and organization
041 * </ul>
042 *
043 * <h5 class='figure'>Schema</h5>
044 * <p class='bschema'>
045 *    atomCategory =
046 *       element atom:category {
047 *          atomCommonAttributes,
048 *          attribute term { text },
049 *          attribute scheme { atomUri }?,
050 *          attribute label { text }?,
051 *          undefinedContent
052 *       }
053 * </p>
054 *
055 * <h5 class='section'>Example:</h5>
056 * <p class='bjava'>
057 *    <jc>// Simple category</jc>
058 *    Category <jv>cat1</jv> = <jk>new</jk> Category(<js>"technology"</js>);
059 *
060 *    <jc>// Category with scheme and label</jc>
061 *    Category <jv>cat2</jv> = <jk>new</jk> Category(<js>"tech"</js>)
062 *       .setScheme(<js>"http://example.org/categories"</js>)
063 *       .setLabel(<js>"Technology"</js>);
064 *
065 *    <jc>// Add to entry</jc>
066 *    Entry <jv>entry</jv> = <jk>new</jk> Entry(...)
067 *       .setCategories(<jv>cat1</jv>, <jv>cat2</jv>);
068 * </p>
069 *
070 * <h5 class='section'>Specification:</h5>
071 * <p>
072 * Represents an <c>atomCategory</c> construct in the 
073 * <a class="doclink" href="https://tools.ietf.org/html/rfc4287#section-4.2.2">RFC 4287 - Section 4.2.2</a> specification.
074 *
075 * <h5 class='section'>See Also:</h5><ul>
076 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanAtom">juneau-bean-atom</a>
077 *    <li class='extlink'><a class="doclink" href="https://tools.ietf.org/html/rfc4287">RFC 4287 - The Atom Syndication Format</a>
078 * </ul>
079 */
080@Bean(typeName="category")
081public class Category extends Common {
082
083   private String term;
084   private URI scheme;
085   private String label;
086
087   /**
088    * Normal constructor.
089    *
090    * @param term The category term.
091    */
092   public Category(String term) {
093      setTerm(term);
094   }
095
096   /** Bean constructor. */
097   public Category() {}
098
099
100   //-----------------------------------------------------------------------------------------------------------------
101   // Bean properties
102   //-----------------------------------------------------------------------------------------------------------------
103
104   /**
105    * Bean property getter:  <property>term</property>.
106    *
107    * <p>
108    * The category term.
109    *
110    * @return The property value, or <jk>null</jk> if it is not set.
111    */
112   @Xml(format=ATTR)
113   public String getTerm() {
114      return term;
115   }
116
117   /**
118    * Bean property setter:  <property>term</property>.
119    *
120    * <p>
121    * The category term.
122    *
123    * @param value
124    *    The new value for this property.
125    *    <br>Can be <jk>null</jk> to unset the property.
126    * @return This object
127    */
128   @Xml(format=ATTR)
129   public Category setTerm(String value) {
130      this.term = value;
131      return this;
132   }
133
134   /**
135    * Bean property getter:  <property>scheme</property>.
136    *
137    * <p>
138    * The category scheme.
139    *
140    * @return The property value, or <jk>null</jk> if it is not set.
141    */
142   @Xml(format=ATTR)
143   public URI getScheme() {
144      return scheme;
145   }
146
147   /**
148    * Bean property setter:  <property>scheme</property>.
149    *
150    * <p>
151    * The category scheme.
152    *
153    * <p>
154    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
155    * Strings must be valid URIs.
156    *
157    * @param value
158    *    The new value for this property.
159    *    <br>Can be <jk>null</jk> to unset the property.
160    * @return This object
161    */
162   public Category setScheme(Object value) {
163      this.scheme = toURI(value);
164      return this;
165   }
166
167   /**
168    * Bean property getter:  <property>label</property>.
169    *
170    * <p>
171    * The category label.
172    *
173    * @return The property value, or <jk>null</jk> if it is not set.
174    */
175   @Xml(format=ATTR)
176   public String getLabel() {
177      return label;
178   }
179
180   /**
181    * Bean property setter:  <property>scheme</property>.
182    *
183    * <p>
184    * The category label.
185    *
186    * @param value
187    *    The new value for this property.
188    *    <br>Can be <jk>null</jk> to unset the property.
189    * @return This object
190    */
191   public Category setLabel(String value) {
192      this.label = value;
193      return this;
194   }
195
196   //-----------------------------------------------------------------------------------------------------------------
197   // Overridden setters (to simplify method chaining)
198   //-----------------------------------------------------------------------------------------------------------------
199
200   @Override /* Overridden from Common */
201   public Category setBase(Object value) {
202      super.setBase(value);
203      return this;
204   }
205
206   @Override /* Overridden from Common */
207   public Category setLang(String value) {
208      super.setLang(value);
209      return this;
210   }
211}