KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > outerj > daisy > repository > Repository


1 /*
2  * Copyright 2004 Outerthought bvba and Schaubroeck nv
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16 package org.outerj.daisy.repository;
17
18 import org.outerj.daisy.repository.schema.RepositorySchema;
19 import org.outerj.daisy.repository.user.UserManager;
20 import org.outerj.daisy.repository.acl.AccessManager;
21 import org.outerj.daisy.repository.query.QueryManager;
22 import org.outerj.daisy.repository.comment.CommentManager;
23 import org.outerj.daisy.repository.variant.VariantManager;
24 import org.outerx.daisy.x10.UserInfoDocument;
25
26 import java.io.InputStream JavaDoc;
27
28 /**
29  * Start point for a user to access the repository.
30  *
31  * <p>An instance of this object is obtained from the {@link RepositoryManager} and
32  * is contextualized for a certain user. Thus instead of having to supply
33  * credentials to each method, you authenticate once via the RepositoryManager
34  * and can then do all further operations on this Repository object.
35  */

36 public interface Repository {
37
38     /**
39      * Creates a new document. You need to supply:
40      * <ul>
41      * <li>a name for the document (which is not required to be unique)
42      * <li>a document type id. This is the id of one of the document types defined in the
43      * {@link RepositorySchema}.
44      * <li>a branch id
45      * <li>a language id
46      * </ul>
47      *
48      * <p>The document will not be stored physically
49      * in the repository until {@link Document#save()} is called. Thus
50      * calling this method has no permanent side effects.
51      */

52     public Document createDocument(String JavaDoc name, long documentTypeId, long branchId, long languageId);
53
54     /**
55      * Same as {@link #createDocument(String, long, long, long)} but takes names instead
56      * of ids.
57      */

58     public Document createDocument(String JavaDoc name, String JavaDoc documentTypeName, String JavaDoc branchName, String JavaDoc languageName);
59
60     /**
61      * Same as {@link #createDocument(String, long, long, long)} but assumes branch id 1
62      * and language id 1.
63      */

64     public Document createDocument(String JavaDoc name, long documentTypeId);
65
66     /**
67      * Same as {@link #createDocument(String, long)} but takes a document type
68      * name instead of an id.
69      */

70     public Document createDocument(String JavaDoc name, String JavaDoc documentTypeName);
71
72     /**
73      * Creates a new variant on a document. If the copyContent argument is true,
74      * the new variant will be immediately persisted and its first version will
75      * be initialiased with the data from the start variant. The start variant
76      * and version will also be stored in the variant (retrievable via
77      * {@link Document#getVariantCreatedFromBranchId()} etc. methods).
78      * If copyContent is false, a document object for the new variant will
79      * be returned, with no data copied from the start variant (except for
80      * the document name), and the new variant will not yet be persisted
81      * (i.o.w. you need to call save on the returned Document object to do
82      * this). Thus using copyContent = false allows to create a variant
83      * from scratch, while copyContent = true branches of from an existing
84      * variant.
85      *
86      * @param startVersionId -1 for last version, -2 for live version
87      */

88     public Document createVariant(long documentId, long startBranchId, long startLanguageId, long startVersionId, long newBranchId, long newLanguageId, boolean copyContent) throws RepositoryException;
89
90     public Document createVariant(long documentId, String JavaDoc startBranchName, String JavaDoc startLanguageName, long startVersionId, String JavaDoc newBranchName, String JavaDoc newLanguageName, boolean copyContent) throws RepositoryException;
91
92     /**
93      * Gets a document from the repository.
94      *
95      * @param updateable if false, you won't be able to make modifications
96      * to the document (and thus to save it). The repository
97      * can return a cached copy in this case.
98      *
99      * @throws DocumentReadDeniedException if read access to the document is denied.
100      */

101     public Document getDocument(long documentId, long branchId, long languageId, boolean updateable) throws RepositoryException;
102
103     /**
104      *
105      * @param branchName a branch name, or a branch id as string
106      * @param languageName a language name, or a language id as string
107      */

108     public Document getDocument(long documentId, String JavaDoc branchName, String JavaDoc languageName, boolean updateable) throws RepositoryException;
109
110     public Document getDocument(VariantKey key, boolean updateable) throws RepositoryException;
111
112     public Document getDocument(long documentId, boolean updateable) throws RepositoryException;
113
114     /**
115      * Gets the available variants of a document. This returns all variants, also the
116      * variants the user may not have access too, and retired variants. Everyone can retrieve the list
117      * of available variants of each document, there is no security constraint to
118      * this. This information is not really sensitive, and access control works on
119      * document variants and not on documents, so it would be a bit difficult to do this.
120      */

121     public AvailableVariants getAvailableVariants(long documentId) throws RepositoryException;
122
123     /**
124      * Deletes a document permanently (unrecoverable) from the repository
125      * (including all its variants).
126      */

127     public void deleteDocument(long documentId) throws RepositoryException;
128
129     /**
130      * @see #deleteVariant(VariantKey)
131      */

132     public void deleteVariant(long documentId, long branchId, long languageId) throws RepositoryException;
133
134     /**
135      * Deletes a document variant permanently (unrecoverable) from the repository.
136      *
137      * <p>To delete a document variant virtually, but not permanently, you can set it
138      * retired (see {@link Document#setRetired(boolean)}).
139      */

140     public void deleteVariant(VariantKey variantKey) throws RepositoryException;
141
142     /**
143      * Retrieves the specified blob without the need to go through the Document object.
144      * Of course, all access control checks still apply.
145      *
146      * @throws DocumentReadDeniedException if read access to the document is denied.
147      */

148     public InputStream JavaDoc getPartData(long documentId, long branchId, long languageId, long versionId, long partTypeId) throws RepositoryException;
149
150     /**
151      * Retrieves part data for the branch "main", language "default".
152      */

153     public InputStream JavaDoc getPartData(long documentId, long versionId, long partTypeId) throws RepositoryException;
154
155     public RepositorySchema getRepositorySchema();
156
157     public AccessManager getAccessManager();
158
159     public QueryManager getQueryManager();
160
161     public CommentManager getCommentManager();
162
163     public VariantManager getVariantManager();
164
165     /**
166      * Returns the Collection Manager for this Repository.
167      */

168     public CollectionManager getCollectionManager();
169
170     /**
171      * Returns the User Manager for this Repository
172      */

173     public UserManager getUserManager();
174
175     /**
176      * Id of the user with who this Repository instance is associated.
177      */

178     public long getUserId();
179
180     /**
181      * The name of the user with who this Repository instance is associated, the
182      * same as returned from {@link org.outerj.daisy.repository.user.User#getDisplayName()}.
183      */

184     public String JavaDoc getUserDisplayName();
185
186     /**
187      * The login of the user with who this Repository instance is associated.
188      */

189     public String JavaDoc getUserLogin();
190
191     /**
192      * The roles of the user that are currently active. These can be changed
193      * through {@link #setActiveRoleIds}.
194      */

195     public long[] getActiveRoleIds();
196
197     public boolean isInRole(long roleId);
198
199     public boolean isInRole(String JavaDoc roleName);
200
201     /**
202      * Sets the active roles of the user.
203      *
204      * @param roleIds a subset of, or equal to, the roles returned by {@link #getAvailableRoles()}.
205      */

206     public void setActiveRoleIds(long[] roleIds);
207
208     /**
209      * Returns the names of the active roles.
210      */

211     public String JavaDoc[] getActiveRolesDisplayNames();
212
213     /**
214      * The id's of the available roles of the user.
215      */

216     public long[] getAvailableRoles();
217
218     /**
219      * Changes the user's role for this Repository instance. This is the same as
220      * calling {@link #setActiveRoleIds(long[])} with a one-length array.
221      *
222      * @param roleId a valid roleId, thus one of those returned by {@link #getAvailableRoles()}.
223      */

224     public void switchRole(long roleId);
225
226     /**
227      * Returns an XML document containing some information about the user
228      * with which this Repository instance is associated.
229      */

230     public UserInfoDocument getUserInfoAsXml();
231
232     /**
233      * Add an event listener.
234      *
235      * <p>See also the comments in {@link RepositoryListener}.
236      *
237      * <p>Not all events are per-se also implemented in the repository client,
238      * and for so far as they are, they only provide events for operations done
239      * through that client, and not other ones happening on the server or through
240      * other clients.
241      *
242      * <p>This listener functionality is mostly meant for internal use, usually
243      * to clear caches. <b>For most usecases you should use the JMS-based (assynchronous)
244      * event notification system.</b>
245      *
246      * <p>A listener stays in effect until it is removed using
247      * {@link #removeListener(org.outerj.daisy.repository.RepositoryListener)}.
248      */

249     public void addListener(RepositoryListener listener);
250
251     /**
252      * Removes an event listener.
253      */

254     public void removeListener(RepositoryListener listener);
255
256     /**
257      * Retrieves an extension of the standard repository functionality.
258      * Extensions are additional available repository services.
259      * What these services are is not defined by this API.
260      *
261      * <p>The reason for making this extension functionality part of the
262      * Repository API, instead of using completely separate and standalone
263      * components, is that in this way the extensions can operate in the
264      * authenticated context of the current user (ie Repository instance).
265      *
266      * <p>So, for as far as the extension performs any operations that depend
267      * on the current user and its role, the extension will operate using the
268      * same credentials as associated with the Repository object from which
269      * the extension instance has been retrieved.
270      */

271     public Object JavaDoc getExtension(String JavaDoc name);
272
273     /**
274      * Gets the version of the Daisy client API. Inside the repository server,
275      * this will be the same as {@link #getServerVersion()}.
276      *
277      * <p>At the time of this writing, in the remote API implementation this
278      * will usually also be the same, as the client and server API implementations
279      * evolve together and get the same version numbers assigned.
280      */

281     public String JavaDoc getClientVersion();
282
283     /**
284      * Returns the version number of the Daisy repository server.
285      * Usually follows the format "major.minor.patch", in which the ".patch"
286      * is optional, and the version string can be followed with
287      * a suffix like "-dev".
288      */

289     public String JavaDoc getServerVersion();
290 }
291
Popular Tags