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.*;
025import org.apache.juneau.annotation.*;
026import org.apache.juneau.xml.annotation.*;
027
028/**
029 * Represents a small icon image for visual identification of a feed.
030 *
031 * <p>
032 * The icon element contains a URI reference to a small image that provides iconic visual 
033 * identification for the feed. Icons are typically small, square images suitable for display 
034 * in feed readers and aggregators.
035 *
036 * <p>
037 * Per RFC 4287 recommendations:
038 * <ul class='spaced-list'>
039 *    <li>Should be square (aspect ratio of 1:1)
040 *    <li>Should be small (e.g., 16x16, 32x32 pixels)
041 *    <li>Common formats: PNG, ICO, GIF
042 * </ul>
043 *
044 * <h5 class='figure'>Schema</h5>
045 * <p class='bschema'>
046 *    atomIcon = element atom:icon {
047 *       atomCommonAttributes,
048 *       (atomUri)
049 *    }
050 * </p>
051 *
052 * <h5 class='section'>Example:</h5>
053 * <p class='bjava'>
054 *    Icon <jv>icon</jv> = <jk>new</jk> Icon(<js>"http://example.org/icon.png"</js>);
055 *
056 *    Feed <jv>feed</jv> = <jk>new</jk> Feed(...)
057 *       .setIcon(<jv>icon</jv>);
058 * </p>
059 *
060 * <h5 class='section'>Specification:</h5>
061 * <p>
062 * Represents an <c>atomIcon</c> construct in the 
063 * <a class="doclink" href="https://tools.ietf.org/html/rfc4287#section-4.2.5">RFC 4287 - Section 4.2.5</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 */
070@Bean(typeName="icon")
071public class Icon extends Common {
072
073   private URI uri;
074
075
076   /**
077    * Normal constructor.
078    *
079    * <p>
080    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
081    * Strings must be valid URIs.
082    *
083    * <p>
084    * URIs defined by {@link UriResolver} can be used for values.
085    *
086    * @param uri The URI of the icon.
087    */
088   public Icon(Object uri) {
089      setUri(uri);
090   }
091
092   /** Bean constructor. */
093   public Icon() {}
094
095
096   //-----------------------------------------------------------------------------------------------------------------
097   // Bean properties
098   //-----------------------------------------------------------------------------------------------------------------
099
100   /**
101    * Bean property getter:  <property>uri</property>.
102    *
103    * <p>
104    * The URI of this icon.
105    *
106    * @return The property value, or <jk>null</jk> if it is not set.
107    */
108   @Xml(format=TEXT)
109   public URI getUri() {
110      return uri;
111   }
112
113   /**
114    * Bean property setter:  <property>uri</property>.
115    *
116    * <p>
117    * The URI of this icon.
118    *
119    * <p>
120    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
121    * Strings must be valid URIs.
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   public Icon setUri(Object value) {
129      this.uri = toURI(value);
130      return this;
131   }
132
133   //-----------------------------------------------------------------------------------------------------------------
134   // Overridden setters (to simplify method chaining)
135   //-----------------------------------------------------------------------------------------------------------------
136
137   @Override /* Overridden from Common */
138   public Icon setBase(Object value) {
139      super.setBase(value);
140      return this;
141   }
142
143   @Override /* Overridden from Common */
144   public Icon setLang(String value) {
145      super.setLang(value);
146      return this;
147   }
148}