Syndication

mapper.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2006 Frank Osterfeld <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef SYNDICATION_MAPPER_H
9 #define SYNDICATION_MAPPER_H
10 
11 #include "syndication_export.h"
12 
13 namespace Syndication
14 {
15 class SpecificDocument;
16 //@cond PRIVATE
17 typedef QSharedPointer<SpecificDocument> SpecificDocumentPtr;
18 //@endcond
19 
20 /**
21  * @brief A mapper maps an SpecificDocument to something else.
22  * The type of this "something else" is specified by the template
23  * parameter T.
24  * In the default implementation it is used with the Feed interface,
25  * but it is not limited to that. T can be an arbitrary class.
26  *
27  * There are three (advanced and hopefully rare) use cases
28  * that require you to implement your own mapper.
29  * For more information on the possible uses, see TODO: link docs.
30  *
31  * 1) Add your own feed parser. In case you need support for another
32  * feed format (Okay! News, CDF, completely backward-incompatible Atom 5.0,
33  * you name it), you can
34  * implement AbstractParser and SpecificDocument for it and provide a
35  * Mapper&lt;Feed>
36  *
37  * * @code
38  * class OkayNewsMapper : public Mapper<Feed>
39  * {
40  * public:
41  *
42  * virtual FeedPtr map(SpecificDocumentPtr doc) const { ... }
43  * };
44  *
45  * parserCollection()->registerParser(new OkayNews::Parser, new OkayNewsMapper);
46  * @endcode
47  *
48  * 2) Implement your own mapper for the Feed abstraction, for an
49  * existing parser. E.g. if you think Syndication does map Atom
50  * all wrong, you can implement your own Atom mapper and use that instead
51  * of the default one.
52  *
53  * @code
54  * class MyAtomMapper : public Mapper<Feed>
55  * {
56  * public:
57  *
58  * virtual FeedPtr map(SpecificDocumentPtr doc) const { ... }
59  * };
60  *
61  * parserCollection()->changeMapper("atom", new MyAtomMapper);
62  * @endcode
63  *
64  * 3) Use your own abstraction. In case the Feed interface
65  * does not fit your needs, you can use your own interface, let's
66  * say "MyFeed". Be aware you have to implement custom mappings for
67  * all feed formats then:
68  *
69  * @code
70  * class MyFeed
71  * {
72  * public:
73  *
74  * QString title() const; // my special title
75  * QList<Article> articles() const; // I name it articles
76  * };
77  *
78  * class MyAtomMapper : public Mapper<MyFeed> { ... };
79  * class MyRDFMapper : public Mapper<MyFeed> { ... };
80  * class MyRSS2Mapper : public Mapper<MyFeed> { ... };
81  *
82  * ParserCollection<MyFeed>* coll = new ParserCollection<MyFeed>;
83  * coll->registerParser(new Atom::Parser, new MyAtomMapper);
84  * coll->registerParser(new RDF::Parser, new MyRDFMapper);
85  coll->registerParser(new RSS2::Parser, new MyRSS2Mapper);
86  * @endcode
87  *
88  * @author Frank Osterfeld
89  */
90 template<class T>
91 class SYNDICATION_EXPORT Mapper
92 {
93 public:
94  /**
95  * virtual destructor
96  */
97  virtual ~Mapper()
98  {
99  }
100 
101  /**
102  * maps a format-specific document to abstraction of type
103  * @c T.
104  *
105  * \note implementations may assume @c doc to have the
106  * type whose mapping they implement and may just statically cast
107  * to the subclass without further checking. If you register your
108  * own mapper, it's your responsibility to register the mapper
109  * only for the format it actually handles.
110  *
111  * @param doc the document to map.
112  * @return a newly created object implementing the abstraction
113  * @c T.
114  */
115  virtual QSharedPointer<T> map(SpecificDocumentPtr doc) const = 0;
116 };
117 
118 } // namespace syndication
119 
120 #endif // SYNDICATION_MAPPER_H
virtual ~Mapper()
virtual destructor
Definition: mapper.h:97
A mapper maps an SpecificDocument to something else.
Definition: mapper.h:91
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 03:57:11 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.