Syndication

mapper.h
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
13namespace Syndication
14{
15class SpecificDocument;
16//@cond PRIVATE
17typedef 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 */
90template<class T>
91class SYNDICATION_EXPORT Mapper
92{
93public:
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
A mapper maps an SpecificDocument to something else.
Definition mapper.h:92
virtual QSharedPointer< T > map(SpecificDocumentPtr doc) const =0
maps a format-specific document to abstraction of type T.
virtual ~Mapper()
virtual destructor
Definition mapper.h:97
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:56:56 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.