File: Database.h

package info (click to toggle)
grr.app 1.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 3,948 kB
  • ctags: 118
  • sloc: objc: 4,019; sh: 72; makefile: 18
file content (215 lines) | stat: -rw-r--r-- 6,121 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
/*
   Grr RSS Reader
   
   Copyright (C) 2006-2007 Guenther Noack <guenther@unix-ag.uni-kl.de>
   Copyright (C) 2009-2010  GNUstep Application Team
                            Riccardo Mottola

   This application is free software; you can redistribute it and/or
   modify it under the terms of the GNU General Public
   License as published by the Free Software Foundation; either
   version 3 of the License, or (at your option) any later version.
 
   This application is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.
 
   You should have received a copy of the GNU General Public
   License along with this library; if not, write to the Free
   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA. 
*/

#import <Foundation/NSObject.h>

#import "Article.h"
#import "Feed.h"

#import "DatabaseElement.h"
#import "ArticleGroup.h"
#import "Category.h"
#import "Components.h"

extern NSString* const DatabaseChangeNotification;

/**
 * Objects conforming to this protocol provide access to a
 * hierarchical database of article groups (e.g. a feed) and
 * categories.
 * 
 * The top level elements of the database conform to the
 * DatabaseElement protocol. The hierarchy is established by its
 * subprotocol 'Category'. A category object stores an array of
 * Database element. (Composite pattern)
 * 
 * The other subprotocol of DatabaseElement is ArticleGroup. An
 * article group stores and provides access to a set of articles.
 * The Feed protocol is also a subprotocol of ArticleGroup.
 */
@protocol Database <NSObject, OutputProvidingComponent>

// ----------------------------------------------------------
//    Retrieval
// ----------------------------------------------------------

/**
 * Returns the top level elements of the database. This
 * is an array of objects conforming to the DatabaseElement
 * protocol.
 */
-(NSArray*)topLevelElements;

/**
 * Returns the set of all articles in the database. An
 * article is an object conforming to the Article protocol.
 */
-(NSSet*)articles;


// ----------------------------------------------------------
//    Modification
// ----------------------------------------------------------

/**
 * Removes the given article object from the database. If the
 * operation succeeds, YES is returned. Otherwise, NO is
 * returned.
 *
 * @return YES on success
 */
-(BOOL)removeArticle: (id<Article>)article;

/**
 * Removed the given database element from the database. If
 * the operation succeeds, YES is returned.
 *
 * @return YES on success
 */
-(BOOL)removeElement: (id<DatabaseElement>)element;

/**
 * Starts the fetching process of all feeds contained in the
 * database. Please note that feeds are not guaranteed to be
 * done with fetching when this method returns. See the Feed
 * protocol on how to find out whether a feed is currently
 * being fetched.
 */
-(void)fetchAllFeeds;

/**
 * Subscribes to the given URL.
 * This is a convenience method for
 * -subscribeToURL:inCategory:position:.
 *
 * @return YES on success
 */
-(BOOL)subscribeToURL: (NSURL*)aURL;

/**
 * Subscribes to the given URL and inserts the newly
 * created feed in the given category. If the given category
 * is nil, the feed will be inserted as top level object in
 * the database.
 * 
 * This is a convenience method for
 * -subscribeToURL:inCategory:position:.
 *
 * @return YES on success
 */
-(BOOL)subscribeToURL: (NSURL*)aURL
           inCategory: (id<Category>)aCategory;

/**
 * Subscribes to the given URL. The newly created feed database
 * element will be created in the given category at the given
 * position. If the category is nil, it will be inserted as top
 * level object in the database. The method returns YES on success,
 * NO on failure.
 * 
 * The method fails if a feed with the given URL is already
 * subscribed. It may also fail if the insertion into the database
 * doesn't work, for example if the index is not valid for the
 * given category.
 * 
 * @return YES on success
 */
-(BOOL)subscribeToURL: (NSURL*)aURL
           inCategory: (id<Category>)aCategory
             position: (int)index;

/**
 * Creates a new category with the given name in the specified
 * category at the given position.
 * 
 * @return YES on success
 */
-(BOOL) addCategoryNamed: (NSString*)name
              inCategory: (id<Category>)aCategory
                position: (int)index;

/**
 * Creates a new category with the given name in the specified
 * category.
 * 
 * @return YES on success
 */
-(BOOL) addCategoryNamed: (NSString*)name
              inCategory: (id<Category>)aCategory;

/**
 * Moves a database element from its old position into the given
 * category.
 * 
 * @return YES on success
 */
-(BOOL)moveElement: (id<DatabaseElement>)anElement
      intoCategory: (id<Category>)aCategory;

/**
 * Moves a database element from its old position into the given
 * category at the given position.
 * 
 * This may especially fail in the case when trying to move a
 * category into itself.
 * 
 * @return YES on success
 */
-(BOOL)moveElement: (id<DatabaseElement>)anElement
      intoCategory: (id<Category>)aCategory
          position: (int)index;

// -------------------------------------------------------------------
//    Archiving
// -------------------------------------------------------------------

/**
 * Writes the database back to its central storage. This method is
 * called by the application before exiting.
 * 
 * Database implementations may also leave this method empty and
 * synchronize with the central storage on the fly.
 * 
 * @return YES on success
 */
-(BOOL)archive;

/**
 * Loads the database from a central storage.
 * 
 * Implementers of a database should call this from the
 * database's -init method.
 * 
 * @return YES on success
 */
-(BOOL)unarchive;

@end

@interface Database : NSObject
/**
 * Singleton method. Returns the one database object for the
 * application.
 */
+(id<Database>) shared;
@end