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    * Bean property getter:  <property>generator</property>.
102    *
103    * <p>
104    * The generator info of this source.
105    *
106    * @return The property value, or <jk>null</jk> if it is not set.
107    */
108   public Generator getGenerator() { return generator; }
109
110   /**
111    * Bean property getter:  <property>icon</property>.
112    *
113    * <p>
114    * The icon of this source.
115    *
116    * @return The property value, or <jk>null</jk> if it is not set.
117    */
118   public Icon getIcon() { return icon; }
119
120   /**
121    * Bean property getter:  <property>logo</property>.
122    *
123    * <p>
124    * The logo of this source.
125    *
126    * @return The property value, or <jk>null</jk> if it is not set.
127    */
128   public Logo getLogo() { return logo; }
129
130   /**
131    * Bean property getter:  <property>subtitle</property>.
132    *
133    * <p>
134    * The subtitle of this source.
135    *
136    * @return The property value, or <jk>null</jk> if it is not set.
137    */
138   public Text getSubtitle() { return subtitle; }
139
140   @Override /* Overridden from CommonEntry */
141   public Source setAuthors(Person...value) {
142      super.setAuthors(value);
143      return this;
144   }
145
146   @Override /* Overridden from Common */
147   public Source setBase(Object value) {
148      super.setBase(value);
149      return this;
150   }
151
152   @Override /* Overridden from CommonEntry */
153   public Source setCategories(Category...value) {
154      super.setCategories(value);
155      return this;
156   }
157
158   @Override /* Overridden from CommonEntry */
159   public Source setContributors(Person...value) {
160      super.setContributors(value);
161      return this;
162   }
163
164   /**
165    * Bean property setter:  <property>generator</property>.
166    *
167    * <p>
168    * The generator info of this source.
169    *
170    * @param value
171    *    The new value for this property.
172    *    <br>Can be <jk>null</jk> to unset the property.
173    * @return This object
174    */
175   public Source setGenerator(Generator value) {
176      generator = value;
177      return this;
178   }
179
180   /**
181    * Bean property setter:  <property>icon</property>.
182    *
183    * <p>
184    * The icon of this source.
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 Source setIcon(Icon value) {
192      icon = value;
193      return this;
194   }
195
196   @Override /* Overridden from CommonEntry */
197   public Source setId(Id value) {
198      super.setId(value);
199      return this;
200   }
201
202   @Override /* Overridden from CommonEntry */
203   public Source setId(String value) {
204      super.setId(value);
205      return this;
206   }
207
208   @Override /* Overridden from Common */
209   public Source setLang(String value) {
210      super.setLang(value);
211      return this;
212   }
213
214   @Override /* Overridden from CommonEntry */
215   public Source setLinks(Link...value) {
216      super.setLinks(value);
217      return this;
218   }
219
220   /**
221    * Bean property setter:  <property>logo</property>.
222    *
223    * <p>
224    * The logo of this source.
225    *
226    * @param value
227    *    The new value for this property.
228    *    <br>Can be <jk>null</jk> to unset the property.
229    * @return This object
230    */
231   public Source setLogo(Logo value) {
232      logo = value;
233      return this;
234   }
235
236   @Override /* Overridden from CommonEntry */
237   public Source setRights(String value) {
238      super.setRights(value);
239      return this;
240   }
241
242   @Override /* Overridden from CommonEntry */
243   public Source setRights(Text value) {
244      super.setRights(value);
245      return this;
246   }
247
248   /**
249    * Bean property fluent setter:  <property>subtitle</property>.
250    *
251    * <p>
252    * The subtitle of this source.
253    *
254    * @param value
255    *    The new value for this property.
256    *    <br>Can be <jk>null</jk> to unset the property.
257    * @return This object.
258    */
259   public Source setSubtitle(String value) {
260      setSubtitle(new Text(value));
261      return this;
262   }
263
264   /**
265    * Bean property setter:  <property>subtitle</property>.
266    *
267    * <p>
268    * The subtitle of this source.
269    *
270    * @param value
271    *    The new value for this property.
272    *    <br>Can be <jk>null</jk> to unset the property.
273    * @return This object
274    */
275   public Source setSubtitle(Text value) {
276      subtitle = value;
277      return this;
278   }
279
280   @Override /* Overridden from CommonEntry */
281   public Source setTitle(String value) {
282      super.setTitle(value);
283      return this;
284   }
285
286   @Override /* Overridden from CommonEntry */
287   public Source setTitle(Text value) {
288      super.setTitle(value);
289      return this;
290   }
291
292   @Override /* Overridden from CommonEntry */
293   public Source setUpdated(Calendar value) {
294      super.setUpdated(value);
295      return this;
296   }
297
298   @Override /* Overridden from CommonEntry */
299   public Source setUpdated(String value) {
300      super.setUpdated(value);
301      return this;
302   }
303}