Skip to content

Commit d0be51c

Browse files
sammeffordsammefford
committed
add javadoc about when we throw ResourceNotFoundException
(cherry picked from commit bb3c6a8)
1 parent 09016f9 commit d0be51c

File tree

1 file changed

+38
-4
lines changed

1 file changed

+38
-4
lines changed

‎src/main/java/com/marklogic/client/document/DocumentManager.java‎

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -95,24 +95,26 @@ public enum Metadata {
9595
public DocumentMetadataPatchBuilder newPatchBuilder(Format pathFormat);
9696

9797
/**
98-
* Checks whether a document exists and gets its format and mimetype
98+
* Checks whether a document exists and gets its byte length, format, mimetype, and version
99+
* if it does.
99100
*
100101
* To call exists(), an application must authenticate as rest-reader, rest-writer, or rest-admin.
101102
*
102103
* @param docId the URI identifier for the document
103-
* @return a descriptor for the document
104+
* @return a descriptor for the document or null if the document is not found
104105
*/
105106
public DocumentDescriptor exists(String docId)
106107
throws ForbiddenUserException, FailedRequestException;
107108

108109
/**
109-
* Checks whether a document exists in an open transaction and gets its length and format
110+
* Checks whether a document exists in an open transaction and gets its byte length, format,
111+
* mimetype, and version if it does.
110112
*
111113
* To call exists(), an application must authenticate as rest-reader, rest-writer, or rest-admin.
112114
*
113115
* @param docId the URI identifier for the document
114116
* @param transaction a open transaction under which the document may have been created or deleted
115-
* @return a descriptor for the document
117+
* @return a descriptor for the document or null if the document is not found
116118
*/
117119
public DocumentDescriptor exists(String docId, Transaction transaction)
118120
throws ForbiddenUserException, FailedRequestException;
@@ -127,6 +129,7 @@ public DocumentDescriptor exists(String docId, Transaction transaction)
127129
* @param as the IO class for reading the content of the document
128130
* @param <T> the type of object that will be returned by the handle registered for it
129131
* @return an object of the IO class with the content of the document in the database
132+
* @throws ResourceNotFoundException if the document is not found
130133
*/
131134
public <T> T readAs(String docId, Class<T> as)
132135
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -141,6 +144,7 @@ public <T> T readAs(String docId, Class<T> as)
141144
* @param transform a server transform to modify the document content
142145
* @param <T> the type of object that will be returned by the handle registered for it
143146
* @return an object of the IO class with the content of the document in the database
147+
* @throws ResourceNotFoundException if the document is not found
144148
*/
145149
public <T> T readAs(String docId, Class<T> as, ServerTransform transform)
146150
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -155,6 +159,7 @@ public <T> T readAs(String docId, Class<T> as, ServerTransform transform)
155159
* @param as the IO class for reading the content of the document
156160
* @param <T> the type of object that will be returned by the handle registered for it
157161
* @return an object of the IO class with the content of the document in the database
162+
* @throws ResourceNotFoundException if the document is not found
158163
*/
159164
public <T> T readAs(String docId, DocumentMetadataReadHandle metadataHandle, Class<T> as)
160165
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -170,6 +175,7 @@ public <T> T readAs(String docId, DocumentMetadataReadHandle metadataHandle, Cla
170175
* @param transform a server transform to modify the document content
171176
* @param <T> the type of object that will be returned by the handle registered for it
172177
* @return an object of the IO class with the content of the document in the database
178+
* @throws ResourceNotFoundException if the document is not found
173179
*/
174180
public <T> T readAs(String docId, DocumentMetadataReadHandle metadataHandle, Class<T> as, ServerTransform transform)
175181
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -183,6 +189,7 @@ public <T> T readAs(String docId, DocumentMetadataReadHandle metadataHandle, Cla
183189
* @param contentHandle a handle for reading the content of the document
184190
* @param <T> the type of content handle to return
185191
* @return the content handle populated with the content of the document in the database
192+
* @throws ResourceNotFoundException if the document is not found
186193
*/
187194
public <T extends R> T read(String docId, T contentHandle)
188195
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -196,6 +203,7 @@ public <T extends R> T read(String docId, T contentHandle)
196203
* @param transform a server transform to modify the document content
197204
* @param <T> the type of content handle to return
198205
* @return the content handle populated with the content of the document in the database
206+
* @throws ResourceNotFoundException if the document is not found
199207
*/
200208
public <T extends R> T read(String docId, T contentHandle, ServerTransform transform)
201209
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -208,6 +216,7 @@ public <T extends R> T read(String docId, T contentHandle, ServerTransform trans
208216
* @param contentHandle a handle for reading the content of the document
209217
* @param <T> the type of content handle to return
210218
* @return the content handle populated with the content of the document in the database
219+
* @throws ResourceNotFoundException if the document is not found
211220
*/
212221
public <T extends R> T read(DocumentDescriptor desc, T contentHandle)
213222
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -221,6 +230,7 @@ public <T extends R> T read(DocumentDescriptor desc, T contentHandle)
221230
* @param transform a server transform to modify the document content
222231
* @param <T> the type of content handle to return
223232
* @return the content handle populated with the content of the document in the database
233+
* @throws ResourceNotFoundException if the document is not found
224234
*/
225235
public <T extends R> T read(DocumentDescriptor desc, T contentHandle, ServerTransform transform)
226236
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -235,6 +245,7 @@ public <T extends R> T read(DocumentDescriptor desc, T contentHandle, ServerTran
235245
* @param contentHandle a handle for reading the content of the document
236246
* @param <T> the type of content handle to return
237247
* @return the content handle populated with the content of the document in the database
248+
* @throws ResourceNotFoundException if the document is not found
238249
*/
239250
public <T extends R> T read(String docId, DocumentMetadataReadHandle metadataHandle, T contentHandle)
240251
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -249,6 +260,7 @@ public <T extends R> T read(String docId, DocumentMetadataReadHandle metadataHan
249260
* @param transform a server transform to modify the document content
250261
* @param <T> the type of content handle to return
251262
* @return the content handle populated with the content of the document in the database
263+
* @throws ResourceNotFoundException if the document is not found
252264
*/
253265
public <T extends R> T read(String docId, DocumentMetadataReadHandle metadataHandle, T contentHandle, ServerTransform transform)
254266
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -262,6 +274,7 @@ public <T extends R> T read(String docId, DocumentMetadataReadHandle metadataHan
262274
* @param contentHandle a handle for reading the content of the document
263275
* @param <T> the type of content handle to return
264276
* @return the content handle populated with the content of the document in the database
277+
* @throws ResourceNotFoundException if the document is not found
265278
*/
266279
public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadataHandle, T contentHandle)
267280
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -276,6 +289,7 @@ public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle
276289
* @param transform a server transform to modify the document content
277290
* @param <T> the type of content handle to return
278291
* @return the content handle populated with the content of the document in the database
292+
* @throws ResourceNotFoundException if the document is not found
279293
*/
280294
public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadataHandle, T contentHandle, ServerTransform transform)
281295
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -290,6 +304,7 @@ public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle
290304
* @param transaction a open transaction under which the document may have been created or deleted
291305
* @param <T> the type of content handle to return
292306
* @return the content handle populated with the content of the document in the database
307+
* @throws ResourceNotFoundException if the document is not found
293308
*/
294309
public <T extends R> T read(String docId, T contentHandle, Transaction transaction)
295310
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -304,6 +319,7 @@ public <T extends R> T read(String docId, T contentHandle, Transaction transacti
304319
* @param transaction a open transaction under which the document may have been created or deleted
305320
* @param <T> the type of content handle to return
306321
* @return the content handle populated with the content of the document in the database
322+
* @throws ResourceNotFoundException if the document is not found
307323
*/
308324
public <T extends R> T read(String docId, T contentHandle, ServerTransform transform, Transaction transaction)
309325
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -317,6 +333,7 @@ public <T extends R> T read(String docId, T contentHandle, ServerTransform trans
317333
* @param transaction a open transaction under which the document may have been created or deleted
318334
* @param <T> the type of content handle to return
319335
* @return the content handle populated with the content of the document in the database
336+
* @throws ResourceNotFoundException if the document is not found
320337
*/
321338
public <T extends R> T read(DocumentDescriptor desc, T contentHandle, Transaction transaction)
322339
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -331,6 +348,7 @@ public <T extends R> T read(DocumentDescriptor desc, T contentHandle, Transactio
331348
* @param transaction a open transaction under which the document may have been created or deleted
332349
* @param <T> the type of content handle to return
333350
* @return the content handle populated with the content of the document in the database
351+
* @throws ResourceNotFoundException if the document is not found
334352
*/
335353
public <T extends R> T read(DocumentDescriptor desc, T contentHandle, ServerTransform transform, Transaction transaction)
336354
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -346,6 +364,7 @@ public <T extends R> T read(DocumentDescriptor desc, T contentHandle, ServerTran
346364
* @param transaction a open transaction under which the document may have been created or deleted
347365
* @param <T> the type of content handle to return
348366
* @return the content handle populated with the content of the document in the database
367+
* @throws ResourceNotFoundException if the document is not found
349368
*/
350369
public <T extends R> T read(String docId, DocumentMetadataReadHandle metadataHandle, T contentHandle, Transaction transaction)
351370
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -361,6 +380,7 @@ public <T extends R> T read(String docId, DocumentMetadataReadHandle metadataHan
361380
* @param transaction a open transaction under which the document may have been created or deleted
362381
* @param <T> the type of content handle to return
363382
* @return the content handle populated with the content of the document in the database
383+
* @throws ResourceNotFoundException if the document is not found
364384
*/
365385
public <T extends R> T read(String docId, DocumentMetadataReadHandle metadataHandle, T contentHandle, ServerTransform transform, Transaction transaction)
366386
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -375,6 +395,7 @@ public <T extends R> T read(String docId, DocumentMetadataReadHandle metadataHan
375395
* @param transaction a open transaction under which the document may have been created or deleted
376396
* @param <T> the type of content handle to return
377397
* @return the content handle populated with the content of the document in the database
398+
* @throws ResourceNotFoundException if the document is not found
378399
*/
379400
public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadataHandle, T contentHandle, Transaction transaction)
380401
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -390,6 +411,7 @@ public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle
390411
* @param transaction a open transaction under which the document may have been created or deleted
391412
* @param <T> the type of content handle to return
392413
* @return the content handle populated with the content of the document in the database
414+
* @throws ResourceNotFoundException if the document is not found
393415
*/
394416
public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadataHandle, T contentHandle, ServerTransform transform, Transaction transaction)
395417
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -859,6 +881,7 @@ public void write(DocumentDescriptor desc, DocumentMetadataWriteHandle metadataH
859881
* To call delete(), an application must authenticate as rest-writer or rest-admin.
860882
*
861883
* @param docId the URI identifier for the document
884+
* @throws ResourceNotFoundException if the document is not found
862885
*/
863886
public void delete(String docId)
864887
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -869,6 +892,7 @@ public void delete(String docId)
869892
*
870893
* @param docId the URI identifier for the document
871894
* @param transaction a open transaction under which the document may have been created or deleted
895+
* @throws ResourceNotFoundException if the document is not found
872896
*/
873897
public void delete(String docId, Transaction transaction)
874898
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -878,6 +902,7 @@ public void delete(String docId, Transaction transaction)
878902
* To call delete(), an application must authenticate as rest-writer or rest-admin.
879903
*
880904
* @param uris the identifiers for the documents to delete
905+
* @throws ResourceNotFoundException if the document is not found
881906
*/
882907
public void delete(String... uris)
883908
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -888,6 +913,7 @@ public void delete(String... uris)
888913
*
889914
* @param transaction an open transaction
890915
* @param uris the identifiers for the documents to delete
916+
* @throws ResourceNotFoundException if the document is not found
891917
*/
892918
public void delete(Transaction transaction, String... uris)
893919
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -897,6 +923,7 @@ public void delete(Transaction transaction, String... uris)
897923
* To call delete(), an application must authenticate as rest-writer or rest-admin.
898924
*
899925
* @param desc a descriptor for the URI identifier, format, and mimetype of the document
926+
* @throws ResourceNotFoundException if the document is not found
900927
*/
901928
public void delete(DocumentDescriptor desc)
902929
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -907,6 +934,7 @@ public void delete(DocumentDescriptor desc)
907934
*
908935
* @param desc a descriptor for the URI identifier, format, and mimetype of the document
909936
* @param transaction a open transaction under which the document may have been created or deleted
937+
* @throws ResourceNotFoundException if the document is not found
910938
*/
911939
public void delete(DocumentDescriptor desc, Transaction transaction)
912940
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -1115,6 +1143,7 @@ public void patchAs(String docId, Object patch)
11151143
* @param metadataHandle a handle for reading the metadata of the document
11161144
* @param <T> the type of DocumentMetadataReadHandle to return
11171145
* @return the metadata handle populated with the metadata for the document in the database
1146+
* @throws ResourceNotFoundException if the document is not found
11181147
*/
11191148
public <T extends DocumentMetadataReadHandle> T readMetadata(String docId, T metadataHandle)
11201149
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -1128,6 +1157,7 @@ public <T extends DocumentMetadataReadHandle> T readMetadata(String docId, T met
11281157
* @param transaction a open transaction under which the document may have been created or deleted
11291158
* @param <T> the type of DocumentMetadataReadHandle to return
11301159
* @return the metadata handle populated with the metadata for the document in the database
1160+
* @throws ResourceNotFoundException if the document is not found
11311161
*/
11321162
public <T extends DocumentMetadataReadHandle> T readMetadata(String docId, T metadataHandle, Transaction transaction)
11331163
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -1139,6 +1169,7 @@ public <T extends DocumentMetadataReadHandle> T readMetadata(String docId, T met
11391169
*
11401170
* @param docId the URI identifier for the document
11411171
* @param metadataHandle a handle for writing the metadata of the document
1172+
* @throws ResourceNotFoundException if the document is not found
11421173
*/
11431174
public void writeMetadata(String docId, DocumentMetadataWriteHandle metadataHandle)
11441175
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -1150,6 +1181,7 @@ public void writeMetadata(String docId, DocumentMetadataWriteHandle metadataHand
11501181
* @param docId the URI identifier for the document
11511182
* @param metadataHandle a handle for writing the metadata of the document
11521183
* @param transaction a open transaction under which the document may have been created or deleted
1184+
* @throws ResourceNotFoundException if the document is not found
11531185
*/
11541186
public void writeMetadata(String docId, DocumentMetadataWriteHandle metadataHandle, Transaction transaction)
11551187
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -1160,6 +1192,7 @@ public void writeMetadata(String docId, DocumentMetadataWriteHandle metadataHand
11601192
* To call writeDefaultMetadata(), an application must authenticate as rest-writer or rest-admin.
11611193
*
11621194
* @param docId the URI identifier for the document
1195+
* @throws ResourceNotFoundException if the document is not found
11631196
*/
11641197
public void writeDefaultMetadata(String docId)
11651198
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;
@@ -1170,6 +1203,7 @@ public void writeDefaultMetadata(String docId)
11701203
*
11711204
* @param docId the URI identifier for the document
11721205
* @param transaction a open transaction under which the document may have been created or deleted
1206+
* @throws ResourceNotFoundException if the document is not found
11731207
*/
11741208
public void writeDefaultMetadata(String docId, Transaction transaction)
11751209
throws ResourceNotFoundException, ForbiddenUserException, FailedRequestException;

0 commit comments

Comments
 (0)