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
019/**
020 * Represents metadata from the source feed when an entry is copied from one feed to another.
021 *
022 * <p>
023 * When entries are aggregated, copied, or republished from their original feed, the source
024 * element preserves metadata about the original feed. This is crucial for proper attribution
025 * and maintaining provenance information.
026 *
027 * <p>
028 * The source element is a child of entry and contains a subset of feed-level metadata that
029 * identifies where the entry originally came from. All child elements are optional, but
030 * including at minimum the source feed's ID, title, and updated timestamp is recommended.
031 *
032 * <p>
033 * Common use cases:
034 * <ul class='spaced-list'>
035 *    <li>Feed aggregation - Combining entries from multiple sources
036 *    <li>Content syndication - Republishing entries from other feeds
037 *    <li>Attribution - Crediting the original source
038 * </ul>
039 *
040 * <h5 class='figure'>Schema</h5>
041 * <p class='bschema'>
042 *    atomSource =
043 *       element atom:source {
044 *          atomCommonAttributes,
045 *          (atomAuthor*
046 *          &amp; atomCategory*
047 *          &amp; atomContributor*
048 *          &amp; atomGenerator?
049 *          &amp; atomIcon?
050 *          &amp; atomId?
051 *          &amp; atomLink*
052 *          &amp; atomLogo?
053 *          &amp; atomRights?
054 *          &amp; atomSubtitle?
055 *          &amp; atomTitle?
056 *          &amp; atomUpdated?
057 *          &amp; extensionElement*)
058 *       }
059 * </p>
060 *
061 * <h5 class='section'>Example:</h5>
062 * <p class='bjava'>
063 *    <jc>// Entry copied from another feed</jc>
064 *    Entry <jv>entry</jv> = <jk>new</jk> Entry(
065 *       <js>"tag:myaggregator.example.com,2024:entry1"</js>,
066 *       <js>"Interesting Article"</js>,
067 *       <js>"2024-01-15T12:00:00Z"</js>
068 *    )
069 *    .setSource(
070 *       <jk>new</jk> Source()
071 *          .setId(<js>"tag:originalblog.example.com,2024:feed"</js>)
072 *          .setTitle(<js>"Original Blog"</js>)
073 *          .setUpdated(<js>"2024-01-15T12:00:00Z"</js>)
074 *          .setLinks(
075 *             <jk>new</jk> Link(<js>"self"</js>, <js>"application/atom+xml"</js>,
076 *                <js>"http://originalblog.example.com/feed.atom"</js>)
077 *          )
078 *    );
079 * </p>
080 *
081 * <h5 class='section'>Specification:</h5>
082 * <p>
083 * Represents an <c>atomSource</c> construct in the
084 * <a class="doclink" href="https://tools.ietf.org/html/rfc4287#section-4.2.11">RFC 4287 - Section 4.2.11</a> specification.
085 *
086 * <h5 class='section'>See Also:</h5><ul>
087 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanAtom">juneau-bean-atom</a>
088 *    <li class='extlink'><a class="doclink" href="https://tools.ietf.org/html/rfc4287">RFC 4287 - The Atom Syndication Format</a>
089 * </ul>
090 */
091public class Source extends CommonEntry<Source> {
092
093   private Generator generator;
094   private Icon icon;
095   private Logo logo;
096   private Text subtitle;
097
098   /**
099    * Bean property getter:  <property>generator</property>.
100    *
101    * <p>
102    * The generator info of this source.
103    *
104    * @return The property value, or <jk>null</jk> if it is not set.
105    */
106   public Generator getGenerator() { return generator; }
107
108   /**
109    * Bean property getter:  <property>icon</property>.
110    *
111    * <p>
112    * The icon of this source.
113    *
114    * @return The property value, or <jk>null</jk> if it is not set.
115    */
116   public Icon getIcon() { return icon; }
117
118   /**
119    * Bean property getter:  <property>logo</property>.
120    *
121    * <p>
122    * The logo of this source.
123    *
124    * @return The property value, or <jk>null</jk> if it is not set.
125    */
126   public Logo getLogo() { return logo; }
127
128   /**
129    * Bean property getter:  <property>subtitle</property>.
130    *
131    * <p>
132    * The subtitle of this source.
133    *
134    * @return The property value, or <jk>null</jk> if it is not set.
135    */
136   public Text getSubtitle() { return subtitle; }
137
138   /**
139    * Bean property setter:  <property>generator</property>.
140    *
141    * <p>
142    * The generator info of this source.
143    *
144    * @param value
145    *    The new value for this property.
146    *    <br>Can be <jk>null</jk> to unset the property.
147    * @return This object
148    */
149   public Source setGenerator(Generator value) {
150      generator = value;
151      return this;
152   }
153
154   /**
155    * Bean property setter:  <property>icon</property>.
156    *
157    * <p>
158    * The icon of this source.
159    *
160    * @param value
161    *    The new value for this property.
162    *    <br>Can be <jk>null</jk> to unset the property.
163    * @return This object
164    */
165   public Source setIcon(Icon value) {
166      icon = value;
167      return this;
168   }
169
170   /**
171    * Bean property setter:  <property>logo</property>.
172    *
173    * <p>
174    * The logo of this source.
175    *
176    * @param value
177    *    The new value for this property.
178    *    <br>Can be <jk>null</jk> to unset the property.
179    * @return This object
180    */
181   public Source setLogo(Logo value) {
182      logo = value;
183      return this;
184   }
185
186   /**
187    * Bean property fluent setter:  <property>subtitle</property>.
188    *
189    * <p>
190    * The subtitle of this source.
191    *
192    * @param value
193    *    The new value for this property.
194    *    <br>Can be <jk>null</jk> to unset the property.
195    * @return This object.
196    */
197   public Source setSubtitle(String value) {
198      setSubtitle(new Text(value));
199      return this;
200   }
201
202   /**
203    * Bean property setter:  <property>subtitle</property>.
204    *
205    * <p>
206    * The subtitle of this source.
207    *
208    * @param value
209    *    The new value for this property.
210    *    <br>Can be <jk>null</jk> to unset the property.
211    * @return This object
212    */
213   public Source setSubtitle(Text value) {
214      subtitle = value;
215      return this;
216   }
217}