1 | /* |
2 | * This file is part of the syndication library |
3 | * |
4 | * Copyright (C) 2006 Frank Osterfeld <osterfeld@kde.org> |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Library General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2 of the License, or (at your option) any later version. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Library General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Library General Public License |
17 | * along with this library; see the file COPYING.LIB. If not, write to |
18 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | * Boston, MA 02110-1301, USA. |
20 | * |
21 | */ |
22 | |
23 | #ifndef SYNDICATION_MAPPER_H |
24 | #define SYNDICATION_MAPPER_H |
25 | |
26 | #include "ksyndication_export.h" |
27 | |
28 | namespace boost { |
29 | template <class T> class shared_ptr; |
30 | } |
31 | |
32 | namespace Syndication { |
33 | |
34 | class SpecificDocument; |
35 | //@cond PRIVATE |
36 | typedef boost::shared_ptr<SpecificDocument> SpecificDocumentPtr; |
37 | //@endcond |
38 | |
39 | /** |
40 | * @brief A mapper maps an SpecificDocument to something else. |
41 | * The type of this "something else" is specified by the template |
42 | * parameter T. |
43 | * In the default implementation it is used with the Feed interface, |
44 | * but it is not limited to that. T can be an arbitrary class. |
45 | * |
46 | * There are three (advanced and hopefully rare) use cases |
47 | * that require you to implement your own mapper. |
48 | * For more information on the possible uses, see TODO: link docs. |
49 | * |
50 | * 1) Add your own feed parser. In case you need support for another |
51 | * feed format (Okay! News, CDF, completely backward-incompatible Atom 5.0, |
52 | * you name it), you can |
53 | * implement AbstractParser and SpecificDocument for it and provide a |
54 | * Mapper<Feed> |
55 | * |
56 | * * @code |
57 | * class OkayNewsMapper : public Mapper<Feed> |
58 | * { |
59 | * public: |
60 | * |
61 | * virtual FeedPtr map(SpecificDocumentPtr doc) const { ... } |
62 | * }; |
63 | * |
64 | * parserCollection()->registerParser(new OkayNews::Parser, new OkayNewsMapper); |
65 | * @endcode |
66 | * |
67 | * 2) Implement your own mapper for the Feed abstraction, for an |
68 | * existing parser. E.g. if you think Syndication does map Atom |
69 | * all wrong, you can implement your own Atom mapper and use that instead |
70 | * of the default one. |
71 | * |
72 | * @code |
73 | * class MyAtomMapper : public Mapper<Feed> |
74 | * { |
75 | * public: |
76 | * |
77 | * virtual FeedPtr map(SpecificDocumentPtr doc) const { ... } |
78 | * }; |
79 | * |
80 | * parserCollection()->changeMapper("atom", new MyAtomMapper); |
81 | * @endcode |
82 | * |
83 | * 3) Use your own abstraction. In case the Feed interface |
84 | * does not fit your needs, you can use your own interface, let's |
85 | * say "MyFeed". Be aware you have to implement custom mappings for |
86 | * all feed formats then: |
87 | * |
88 | * @code |
89 | * class MyFeed |
90 | * { |
91 | * public: |
92 | * |
93 | * QString title() const; // my special title |
94 | * QList<Article> articles() const; // I name it articles |
95 | * }; |
96 | * |
97 | * class MyAtomMapper : public Mapper<MyFeed> { ... }; |
98 | * class MyRDFMapper : public Mapper<MyFeed> { ... }; |
99 | * class MyRSS2Mapper : public Mapper<MyFeed> { ... }; |
100 | * |
101 | * ParserCollection<MyFeed>* coll = new ParserCollection<MyFeed>; |
102 | * coll->registerParser(new Atom::Parser, new MyAtomMapper); |
103 | * coll->registerParser(new RDF::Parser, new MyRDFMapper); |
104 | coll->registerParser(new RSS2::Parser, new MyRSS2Mapper); |
105 | * @endcode |
106 | * |
107 | * @author Frank Osterfeld |
108 | */ |
109 | template <class T> |
110 | class SYNDICATION_EXPORT Mapper |
111 | { |
112 | public: |
113 | |
114 | /** |
115 | * virtual destructor |
116 | */ |
117 | virtual ~Mapper() {} |
118 | |
119 | /** |
120 | * maps a format-specific document to abstraction of type |
121 | * @c T. |
122 | * |
123 | * \note implementations may assume @c doc to have the |
124 | * type whose mapping they implement and may just statically cast |
125 | * to the subclass without further checking. If you register your |
126 | * own mapper, it's your responsibility to register the mapper |
127 | * only for the format it actually handles. |
128 | * |
129 | * @param doc the document to map. |
130 | * @return a newly created object implementing the abstraction |
131 | * @c T. |
132 | */ |
133 | virtual boost::shared_ptr<T> map(SpecificDocumentPtr doc) const = 0; |
134 | }; |
135 | |
136 | } // namespace syndication |
137 | |
138 | #endif // SYNDICATION_MAPPER_H |
139 | |