Source code

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 java.util.*;
020
021/**
022 * Represents metadata from the source feed when an entry is copied from one feed to another.
023 *
024 * <p>
025 * When entries are aggregated, copied, or republished from their original feed, the source 
026 * element preserves metadata about the original feed. This is crucial for proper attribution 
027 * and maintaining provenance information.
028 *
029 * <p>
030 * The source element is a child of entry and contains a subset of feed-level metadata that 
031 * identifies where the entry originally came from. All child elements are optional, but 
032 * including at minimum the source feed's ID, title, and updated timestamp is recommended.
033 *
034 * <p>
035 * Common use cases:
036 * <ul class='spaced-list'>
037 *    <li>Feed aggregation - Combining entries from multiple sources
038 *    <li>Content syndication - Republishing entries from other feeds
039 *    <li>Attribution - Crediting the original source
040 * </ul>
041 *
042 * <h5 class='figure'>Schema</h5>
043 * <p class='bschema'>
044 *    atomSource =
045 *       element atom:source {
046 *          atomCommonAttributes,
047 *          (atomAuthor*
048 *          &amp; atomCategory*
049 *          &amp; atomContributor*
050 *          &amp; atomGenerator?
051 *          &amp; atomIcon?
052 *          &amp; atomId?
053 *          &amp; atomLink*
054 *          &amp; atomLogo?
055 *          &amp; atomRights?
056 *          &amp; atomSubtitle?
057 *          &amp; atomTitle?
058 *          &amp; atomUpdated?
059 *          &amp; extensionElement*)
060 *       }
061 * </p>
062 *
063 * <h5 class='section'>Example:</h5>
064 * <p class='bjava'>
065 *    <jc>// Entry copied from another feed</jc>
066 *    Entry <jv>entry</jv> = <jk>new</jk> Entry(
067 *       <js>"tag:myaggregator.example.com,2024:entry1"</js>,
068 *       <js>"Interesting Article"</js>,
069 *       <js>"2024-01-15T12:00:00Z"</js>
070 *    )
071 *    .setSource(
072 *       <jk>new</jk> Source()
073 *          .setId(<js>"tag:originalblog.example.com,2024:feed"</js>)
074 *          .setTitle(<js>"Original Blog"</js>)
075 *          .setUpdated(<js>"2024-01-15T12:00:00Z"</js>)
076 *          .setLinks(
077 *             <jk>new</jk> Link(<js>"self"</js>, <js>"application/atom+xml"</js>, 
078 *                <js>"http://originalblog.example.com/feed.atom"</js>)
079 *          )
080 *    );
081 * </p>
082 *
083 * <h5 class='section'>Specification:</h5>
084 * <p>
085 * Represents an <c>atomSource</c> construct in the 
086 * <a class="doclink" href="https://tools.ietf.org/html/rfc4287#section-4.2.11">RFC 4287 - Section 4.2.11</a> specification.
087 *
088 * <h5 class='section'>See Also:</h5><ul>
089 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanAtom">juneau-bean-atom</a>
090 *    <li class='extlink'><a class="doclink" href="https://tools.ietf.org/html/rfc4287">RFC 4287 - The Atom Syndication Format</a>
091 * </ul>
092 */
093public class Source extends CommonEntry {
094
095   private Generator generator;
096   private Icon icon;
097   private Logo logo;
098   private Text subtitle;
099
100
101   //-----------------------------------------------------------------------------------------------------------------
102   // Bean properties
103   //-----------------------------------------------------------------------------------------------------------------
104
105   /**
106    * Bean property getter:  <property>generator</property>.
107    *
108    * <p>
109    * The generator info of this source.
110    *
111    * @return The property value, or <jk>null</jk> if it is not set.
112    */
113   public Generator getGenerator() {
114      return generator;
115   }
116
117   /**
118    * Bean property setter:  <property>generator</property>.
119    *
120    * <p>
121    * The generator info of this source.
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 Source setGenerator(Generator value) {
129      this.generator = value;
130      return this;
131   }
132
133   /**
134    * Bean property getter:  <property>icon</property>.
135    *
136    * <p>
137    * The icon of this source.
138    *
139    * @return The property value, or <jk>null</jk> if it is not set.
140    */
141   public Icon getIcon() {
142      return icon;
143   }
144
145   /**
146    * Bean property setter:  <property>icon</property>.
147    *
148    * <p>
149    * The icon of this source.
150    *
151    * @param value
152    *    The new value for this property.
153    *    <br>Can be <jk>null</jk> to unset the property.
154    * @return This object
155    */
156   public Source setIcon(Icon value) {
157      this.icon = value;
158      return this;
159   }
160
161   /**
162    * Bean property getter:  <property>logo</property>.
163    *
164    * <p>
165    * The logo of this source.
166    *
167    * @return The property value, or <jk>null</jk> if it is not set.
168    */
169   public Logo getLogo() {
170      return logo;
171   }
172
173   /**
174    * Bean property setter:  <property>logo</property>.
175    *
176    * <p>
177    * The logo of this source.
178    *
179    * @param value
180    *    The new value for this property.
181    *    <br>Can be <jk>null</jk> to unset the property.
182    * @return This object
183    */
184   public Source setLogo(Logo value) {
185      this.logo = value;
186      return this;
187   }
188
189   /**
190    * Bean property getter:  <property>subtitle</property>.
191    *
192    * <p>
193    * The subtitle of this source.
194    *
195    * @return The property value, or <jk>null</jk> if it is not set.
196    */
197   public Text getSubtitle() {
198      return subtitle;
199   }
200
201   /**
202    * Bean property setter:  <property>subtitle</property>.
203    *
204    * <p>
205    * The subtitle of this source.
206    *
207    * @param value
208    *    The new value for this property.
209    *    <br>Can be <jk>null</jk> to unset the property.
210    * @return This object
211    */
212   public Source setSubtitle(Text value) {
213      this.subtitle = value;
214      return this;
215   }
216
217   /**
218    * Bean property fluent setter:  <property>subtitle</property>.
219    *
220    * <p>
221    * The subtitle of this source.
222    *
223    * @param value
224    *    The new value for this property.
225    *    <br>Can be <jk>null</jk> to unset the property.
226    * @return This object.
227    */
228   public Source setSubtitle(String value) {
229      setSubtitle(new Text(value));
230      return this;
231   }
232
233
234   //-----------------------------------------------------------------------------------------------------------------
235   // Overridden setters (to simplify method chaining)
236   //-----------------------------------------------------------------------------------------------------------------
237
238   @Override /* Overridden from Common */
239   public Source setBase(Object value) {
240      super.setBase(value);
241      return this;
242   }
243
244   @Override /* Overridden from Common */
245   public Source setLang(String value) {
246      super.setLang(value);
247      return this;
248   }
249
250   @Override /* Overridden from CommonEntry */
251   public Source setAuthors(Person...value) {
252      super.setAuthors(value);
253      return this;
254   }
255
256   @Override /* Overridden from CommonEntry */
257   public Source setCategories(Category...value) {
258      super.setCategories(value);
259      return this;
260   }
261
262   @Override /* Overridden from CommonEntry */
263   public Source setContributors(Person...value) {
264      super.setContributors(value);
265      return this;
266   }
267
268   @Override /* Overridden from CommonEntry */
269   public Source setId(String value) {
270      super.setId(value);
271      return this;
272   }
273
274   @Override /* Overridden from CommonEntry */
275   public Source setId(Id value) {
276      super.setId(value);
277      return this;
278   }
279
280   @Override /* Overridden from CommonEntry */
281   public Source setLinks(Link...value) {
282      super.setLinks(value);
283      return this;
284   }
285
286   @Override /* Overridden from CommonEntry */
287   public Source setRights(String value) {
288      super.setRights(value);
289      return this;
290   }
291
292   @Override /* Overridden from CommonEntry */
293   public Source setRights(Text value) {
294      super.setRights(value);
295      return this;
296   }
297
298   @Override /* Overridden from CommonEntry */
299   public Source setTitle(String value) {
300      super.setTitle(value);
301      return this;
302   }
303
304   @Override /* Overridden from CommonEntry */
305   public Source setTitle(Text value) {
306      super.setTitle(value);
307      return this;
308   }
309
310   @Override /* Overridden from CommonEntry */
311   public Source setUpdated(String value) {
312      super.setUpdated(value);
313      return this;
314   }
315
316   @Override /* Overridden from CommonEntry */
317   public Source setUpdated(Calendar value) {
318      super.setUpdated(value);
319      return this;
320   }
321}