1 /*
2 * Copyright 2016-2024 Bloomreach B.V. (https://www.bloomreach.com)
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.onehippo.forge.content.exim.core;
17
18 import javax.jcr.Node;
19 import javax.jcr.RepositoryException;
20 import javax.jcr.Session;
21
22 import org.hippoecm.repository.api.Document;
23 import org.onehippo.forge.content.pojo.model.ContentNode;
24 import org.onehippo.repository.documentworkflow.DocumentWorkflow;
25 import org.slf4j.Logger;
26
27 /**
28 * Hippo CMS Document/Folder Workflow manager.
29 */
30 public interface DocumentManager {
31
32 /**
33 * Returns the logger used by DocumentManager.
34 * @return the logger used by DocumentManager
35 */
36 Logger getLogger();
37
38 /**
39 * Sets a logger to DocumentManager.
40 * @param logger the logger to be used by DocumentManager
41 */
42 void setLogger(Logger logger);
43
44 /**
45 * Returns the JCR session.
46 * @return the JCR session
47 */
48 Session getSession();
49
50 /**
51 * Returns true if a document exists at {@code documentLocation}.
52 * @param documentLocation document handle node path
53 * @return true if a document exists at {@code documentLocation}
54 * @throws DocumentManagerException if fails to process
55 */
56 boolean documentExists(String documentLocation) throws DocumentManagerException;
57
58 /**
59 * Returns the physical document handle node path for the logical document location.
60 * Returns null if document doesn't exist at the location, without any exception,
61 * unlike {@link #getExistingDocumentHandleNode(String)}.
62 * @param documentLocation logical document location
63 * @return the physical document handle node path for the logical document location
64 * @throws DocumentManagerException if fails to process
65 */
66 String getExistingDocumentPath(String documentLocation) throws DocumentManagerException;
67
68 /**
69 * Returns the physical document handle node for the logical document location.
70 * Throws a {@link DocumentManagerNotFoundException} if document doesn't exist at the location,
71 * unlike {@link #getExistingDocumentPath(String)}.
72 * @param documentLocation logical document location
73 * @return the physical document handle node for the logical document location
74 * @throws DocumentManagerNotFoundException if cannot find a document
75 * @throws RepositoryException if any repository exception occurs
76 */
77 Node getExistingDocumentHandleNode(String documentLocation) throws DocumentManagerNotFoundException, RepositoryException;
78
79 /**
80 * Returns true if a folder exists at {@code folderLocation}.
81 * @param folderLocation folder node path
82 * @return true if a folder exists at {@code folderLocation}
83 * @throws DocumentManagerException if fails to process
84 */
85 boolean folderExists(String folderLocation) throws DocumentManagerException;
86
87 /**
88 * Returns the physical folder node path for the logical folder location.
89 * Returns null if folder doesn't exist at the location, without any exception,
90 * unlike {@link #getExistingFolderNode(String)}.
91 * @param folderLocation logical folder location
92 * @return the physical folder node path for the logical folder location
93 * @throws DocumentManagerException if fails to process
94 */
95 String getExistingFolderPath(String folderLocation) throws DocumentManagerException;
96
97 /**
98 * Returns the physical folder node for the logical folder location.
99 * Throws a {@link DocumentManagerNotFoundException} if folder doesn't exist at the location,
100 * unlike {@link #getExistingDocumentPath(String)}.
101 * @param folderLocation logical folder location
102 * @return the physical folder node for the logical folder location
103 * @throws DocumentManagerException if cannot find a folder
104 * @throws RepositoryException if any repository exception occurs
105 */
106 Node getExistingFolderNode(String folderLocation) throws DocumentManagerNotFoundException, RepositoryException;
107
108 /**
109 * Creates a document in the specific {@code folderLocation}.
110 * @param folderLocation destination folder path
111 * @param primaryTypeName primary node type name of document to be created
112 * @param nodeName document node name
113 * @param locale locale for the document display name. e.g, "en"
114 * @param localizedName localized document name associated with the {@code locale}
115 * @return created document handle path
116 * @throws DocumentManagerException if fails to process
117 */
118 String createDocument(String folderLocation, String primaryTypeName, String nodeName, String locale,
119 String localizedName) throws DocumentManagerException;
120
121 /**
122 * Obtains an editable draft variant {@link Document} under the given document handle path ({@code documentLocation}).
123 * @param documentLocation document handle path
124 * @return a {@link Document} instance if the operation was successful
125 * @throws DocumentManagerException if fails to process
126 */
127 Document obtainEditableDocument(String documentLocation) throws DocumentManagerException;
128
129 /**
130 * Obtains an editable draft variant {@link Document} of the given document handle node ({@code documentHandleNode}).
131 *
132 * @param documentHandleNode document handle node
133 * @return a {@link Document} instance if the operation was successful
134 * @throws DocumentManagerException if fails to process
135 */
136 Document obtainEditableDocument(Node documentHandleNode) throws DocumentManagerException;
137
138 /**
139 * Update editable {@link Document} instance ({@code editableDocument}) by the content of the given {@code sourceContentNode}.
140 * @param editableDocument {@link Document} instance to edit
141 * @param sourceContentNode source content node
142 * @throws DocumentManagerException if fails to process
143 */
144 void updateEditableDocument(Document editableDocument, ContentNode sourceContentNode)
145 throws DocumentManagerException;
146
147 /**
148 * Discards the draft variant which is currently being edited.
149 * @param documentLocation document handle path
150 * @return {@link Document} instance discarded if the operation was successful
151 * @throws DocumentManagerException if fails to process
152 */
153 Document disposeEditableDocument(String documentLocation) throws DocumentManagerException;
154
155 /**
156 * Discards the draft variant which is currently being edited.
157 * @param editableDocument document object
158 * @return {@link Document} instance discarded if the operation was successful
159 * @throws DocumentManagerException if fails to process
160 */
161 Document disposeEditableDocument(Document editableDocument) throws DocumentManagerException;
162
163 /**
164 * Commits the draft variant which is currently being edited.
165 * @param documentLocation document handle path
166 * @return {@link Document} instance committed if the operation was successful
167 * @throws DocumentManagerException if fails to process
168 */
169 Document commitEditableDocument(String documentLocation) throws DocumentManagerException;
170
171 /**
172 * Commits the draft variant which is currently being edited.
173
174 * @param editableDocument document object
175 * @return {@link Document} instance committed if the operation was successful
176 * @throws DocumentManagerException if fails to process
177 */
178 Document commitEditableDocument(Document editableDocument) throws DocumentManagerException;
179
180
181 /**
182 * Publishes the document at the given document handle path ({@code documentLocation}).
183 * @param documentLocation document handle path
184 * @return true if the operation was successful, false otherwise
185 * @throws DocumentManagerException if fails to process
186 */
187 boolean publishDocument(String documentLocation) throws DocumentManagerException;
188
189 /**
190 * Takes offline the document at the given document handle path ({@code documentLocation}).
191 * @param documentLocation document handle path
192 * @return true if the operation was successful, false otherwise
193 * @throws DocumentManagerException if fails to process
194 */
195 boolean depublishDocument(String documentLocation) throws DocumentManagerException;
196
197 /**
198 * Deletes a document at at the given document handle path ({@code documentLocation}).
199 * @param documentLocation document handle path
200 * @throws DocumentManagerException if fails to process
201 */
202 void deleteDocument(String documentLocation) throws DocumentManagerException;
203
204 /**
205 * Copies a document at the source document handle path ({@code sourceDocumentLocation}) to
206 * the target folder path ({@code targetFolderLocation}) with the given document node name ({@code targetDocumentName}).
207 * @param sourceDocumentLocation source document handle path
208 * @param targetFolderLocation target folder path
209 * @param targetDocumentName target document handle node name
210 * @return the copied target document handle path
211 * @throws DocumentManagerException if fails to process
212 */
213 String copyDocument(String sourceDocumentLocation, String targetFolderLocation, String targetDocumentName)
214 throws DocumentManagerException;
215
216 /**
217 * Translates a folder at the folder path ({@code sourceFolderLocation}) to {@code name} in {@code language}.
218 * @param sourceFolderLocation source folder path
219 * @param language target language to translate to
220 * @param name target folder node name
221 * @return the translated target folder {@code Document} instance
222 * @throws DocumentManagerException if fails to process
223 */
224 Document translateFolder(String sourceFolderLocation, String language, String name) throws DocumentManagerException;
225
226 /**
227 * Translates a document at the document handle path ({@code sourceDocumentLocation}) to {@code name} in {@code language}.
228 * @param sourceDocumentLocation source document handle path
229 * @param language target language to translate to
230 * @param name target document handle node name
231 * @return the translated target document {@code Document} instance
232 * @throws DocumentManagerException if fails to process
233 */
234 Document translateDocument(String sourceDocumentLocation, String language, String name)
235 throws DocumentManagerException;
236
237 /**
238 * Returns a document workflow on {@code documentHandleNode}.
239 * @param documentHandleNode document handle node
240 * @return a document workflow on {@code documentHandleNode}
241 * @throws RepositoryException if unexpected repository exception occurs
242 */
243 public DocumentWorkflow getDocumentWorkflow(final Node documentHandleNode) throws RepositoryException;
244
245 }