1/*
2 This file is part of kdepim.
3
4 Copyright (c) 2004 Tobias Koenig <tokoe@kde.org>
5 Copyright (c) 2004 Cornelius Schumacher <schumacher@kde.org>
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with this library; see the file COPYING.LIB. If not, write to
19 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 Boston, MA 02110-1301, USA.
21*/
22/**
23 @file
24 This file is part of the KDE resource framework and defines the
25 IdMapper class.
26
27 @author Tobias Koenig
28 @author Cornelius Schumacher
29*/
30
31#ifndef KRESOURCES_IDMAPPER_H
32#define KRESOURCES_IDMAPPER_H
33
34#include <QtCore/QMap>
35#include <QtCore/QString>
36
37#include "kresources_export.h"
38
39namespace KRES {
40
41class IdMapperPrivate;
42
43/**
44 @brief
45 Keeps a map of paths and identifiers.
46
47 An Id Mapper maps Ids. What to or what for is not entirely
48 clear, but maps have categories. This is probably an
49 adjoint functor, since adjoint functors are everywhere.
50*/
51class KRESOURCES_DEPRECATED_EXPORT IdMapper
52{
53 public:
54 /**
55 Create Id mapper. You have to set path and identifier before you can call
56 load() or save().
57 */
58 IdMapper();
59
60 /**
61 Create Id mapper. The path specifies the category of mapping, the
62 identifier the concrete object.
63
64 If you don't pass an identifier you have to set it before calling load()
65 or save().
66
67 The current implementation stores the data at
68 $(KDEHOME)/share/apps/\<path\>/\<identifier\>.
69
70 @param path Category of mapping (path into the mapping namespace)
71 @param identifier The concrete mapping object (filename in namespace)
72 */
73 explicit IdMapper( const QString &path,
74 const QString &identifier = QString() );
75
76 /** Destructor. */
77 ~IdMapper();
78
79 /**
80 Set id map path.
81 @param path Path to use into mapping namespace.
82 @see IdMapper()
83 */
84 void setPath( const QString &path );
85
86 /**
87 Return id map path.
88 */
89 QString path() const;
90
91 /**
92 Set id map identifier.
93 @param identifier the identifier (filename) within the mapping namespace
94 */
95 void setIdentifier( const QString &identifier );
96
97 /**
98 Return id map identifier.
99 */
100 QString identifier() const;
101
102 /**
103 Loads the map.
104 */
105 bool load();
106
107 /**
108 Saves the map.
109 */
110 bool save();
111
112 /**
113 Clears the map.
114 */
115 void clear();
116
117 /**
118 Stores the remote id for the given local id.
119 @param localId Local Id to set remote for.
120 @param remoteId Remote Id to associate with this local Id.
121 @see remoteId()
122 @see localId()
123 @todo What happens when you set the same remote Id for more than
124 one localId?
125 */
126 void setRemoteId( const QString &localId, const QString &remoteId );
127
128 /**
129 Removes the remote id.
130 @param remoteId remote Id to remove.
131 @todo So what does that do? Remove local Ids with only that
132 one remote Id? Remove the remote Id from all local Ids
133 that have it?
134 @see setRemoteId()
135 */
136 void removeRemoteId( const QString &remoteId );
137
138 /**
139 Returns the remote id of the given local id.
140 @param localId Local Id to get the remote Id from.
141 @see setRemoteId()
142 @see removeRemoteId()
143 */
144 QString remoteId( const QString &localId ) const;
145
146 /**
147 Returns the local id for the given remote id.
148 @param remoteId Remote Id to get the local Id for.
149 */
150 QString localId( const QString &remoteId ) const;
151
152 /**
153 Stores a fingerprint for an id which can be used to detect if
154 the locally held version differs from what is on the server.
155 This can be a sequence number of an md5 hash depending on what
156 the server provides.
157
158 @param localId Local Id to set the fingerprint on.
159 @param fingerprint Fingerprint (any string will do, though
160 an md5 hash is probably a good idea) of the Id.
161 */
162 void setFingerprint( const QString &localId, const QString &fingerprint );
163
164 /**
165 Returns the fingerprint for the map.
166
167 @param localId Local Id to get the fingerprint for.
168 @todo Figure out if this returns the last fingerprint set
169 by setFingerprint() only or if anything else can change it.
170 */
171 QString fingerprint( const QString &localId ) const;
172
173 /**
174 Returns the entire map of local-to-remote Ids.
175 */
176 QMap<QString, QString> remoteIdMap() const;
177
178 /**
179 Returns a string representation of the id pairs, that's useful
180 for debugging.
181 */
182 QString asString() const;
183
184 protected:
185 /**
186 Filename of the map when stored on disk. Used in save() and load(),
187 @see IdMapper( const QString &path, const QString &identifier )
188 */
189 QString filename();
190
191 private:
192 IdMapperPrivate *const d;
193};
194
195}
196
197#endif
198