1 | /* |
2 | This file is part of the syndication library |
3 | SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org> |
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<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 |
121 | |