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
28namespace boost {
29 template <class T> class shared_ptr;
30}
31
32namespace Syndication {
33
34class SpecificDocument;
35//@cond PRIVATE
36typedef 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&lt;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 */
109template <class T>
110class 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