1 /* 2 * Copyright 2009 The Kuali Foundation 3 * 4 * Licensed under the Educational Community License, Version 1.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.opensource.org/licenses/ecl1.php 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.kuali.student.core.document.service; 17 18 import java.util.List; 19 20 import javax.jws.WebParam; 21 import javax.jws.WebService; 22 import javax.jws.soap.SOAPBinding; 23 24 import org.kuali.student.common.dictionary.service.DictionaryService; 25 import org.kuali.student.common.dto.StatusInfo; 26 import org.kuali.student.common.exceptions.DataValidationErrorException; 27 import org.kuali.student.common.exceptions.DoesNotExistException; 28 import org.kuali.student.common.exceptions.InvalidParameterException; 29 import org.kuali.student.common.exceptions.MissingParameterException; 30 import org.kuali.student.common.exceptions.OperationFailedException; 31 import org.kuali.student.common.exceptions.PermissionDeniedException; 32 import org.kuali.student.common.exceptions.VersionMismatchException; 33 import org.kuali.student.common.validation.dto.ValidationResultInfo; 34 35 36 import org.kuali.student.core.document.dto.DocumentCategoryInfo; 37 import org.kuali.student.core.document.dto.DocumentInfo; 38 import org.kuali.student.core.document.dto.DocumentTypeInfo; 39 import org.kuali.student.core.document.dto.RefDocRelationInfo; 40 import org.kuali.student.core.document.dto.RefDocRelationTypeInfo; 41 42 43 44 /** 45 * 46 * @Author KSContractMojo 47 * @Author tom 48 * @Since Wed Aug 18 12:10:24 EDT 2010 49 * @See <a href="https://test.kuali.org/confluence/display/KULSTU/Document+Service">DocumentService</> 50 * 51 */ 52 @WebService(name = "DocumentService", targetNamespace = "http://student.kuali.org/wsdl/document") // TODO CHECK THESE VALUES 53 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED) 54 public interface DocumentService extends DictionaryService { 55 /** 56 * Retrieves the list of document types known by this service 57 * @return list of document type information 58 * @throws OperationFailedException unable to complete request 59 */ 60 public List<DocumentTypeInfo> getDocumentTypes() throws OperationFailedException; 61 62 /** 63 * Retrieves information about a particular document type 64 * @param documentTypeKey document type identifier 65 * @return document type information 66 * @throws DoesNotExistException specified documentTypeKey not found 67 * @throws InvalidParameterException invalid documentTypeKey 68 * @throws MissingParameterException documentTypeKey not specified 69 * @throws OperationFailedException unable to complete request 70 */ 71 public DocumentTypeInfo getDocumentType(@WebParam(name="documentTypeKey")String documentTypeKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException; 72 73 /** 74 * Retrieves the list of document categories known by this service 75 * @return list of document category information 76 * @throws OperationFailedException unable to complete request 77 */ 78 public List<DocumentCategoryInfo> getDocumentCategories() throws OperationFailedException; 79 80 /** 81 * Retrieves information about a particular document category 82 * @param documentCategoryKey document category identifier 83 * @return document category information 84 * @throws DoesNotExistException specified documentCategoryKey not found 85 * @throws InvalidParameterException invalid documentCategoryKey 86 * @throws MissingParameterException documentCategoryKey not specified 87 * @throws OperationFailedException unable to complete request 88 */ 89 public DocumentCategoryInfo getDocumentCategory(@WebParam(name="documentCategoryKey")String documentCategoryKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException; 90 91 /** 92 * Retrieves the list of base types which can be connected to a document. 93 * @return the list of types which can be connected to a document 94 * @throws OperationFailedException unable to complete request 95 */ 96 public List<String> getRefObjectTypes() throws OperationFailedException; 97 98 /** 99 * Retrieves the list of types for a given base type which can be connected to a document. 100 * @param refObjectTypeKey Reference Type Identifier 101 * @return the list of types for the given base type which can be connected to a document 102 * @throws OperationFailedException unable to complete request 103 */ 104 public List<String> getRefObjectSubTypes(@WebParam(name="refObjectTypeKey")String refObjectTypeKey) throws MissingParameterException, OperationFailedException; 105 106 /** 107 * Retrieves the list of types for a given base type which can be connected to a document. 108 * @return the list of reference document relation types 109 * @throws OperationFailedException unable to complete request 110 */ 111 public List<RefDocRelationTypeInfo> getRefDocRelationTypes() throws OperationFailedException; 112 113 /** 114 * Retrieves the list of reference document relation types which are allowed for a given reference subtype. 115 * @param refSubTypeKey reference subtype 116 * @return the list of reference document relation types which are allowed for a given referenced subtype. 117 * @throws DoesNotExistException specified refSubTypeKey not found 118 * @throws InvalidParameterException invalid refSubTypeKey 119 * @throws MissingParameterException refSubTypeKey not specified 120 * @throws OperationFailedException unable to complete request 121 */ 122 public List<RefDocRelationTypeInfo> getRefDocRelationTypesForRefObjectSubType(@WebParam(name="refSubTypeKey")String refSubTypeKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException; 123 124 /** 125 * Retrieves information about a document. 126 * @param documentId identifier of the document 127 * @return information about a document 128 * @throws DoesNotExistException documentId not found 129 * @throws InvalidParameterException invalid documentId 130 * @throws MissingParameterException missing documentId 131 * @throws OperationFailedException unable to complete request 132 * @throws PermissionDeniedException authorization failure 133 */ 134 public DocumentInfo getDocument(@WebParam(name="documentId")String documentId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 135 136 /** 137 * Retrieves information about documents from a list of identifiers. 138 * @param documentIdList list of document identifiers 139 * @return list of document information 140 * @throws DoesNotExistException one of more documentIds not found 141 * @throws InvalidParameterException one of more invalid documentIds 142 * @throws MissingParameterException missing documentIdList 143 * @throws OperationFailedException unable to complete request 144 * @throws PermissionDeniedException authorization failure 145 */ 146 public List<DocumentInfo> getDocumentsByIdList(@WebParam(name="documentIdList")List<String> documentIdList) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 147 148 /** 149 * Retrieves category information for a document. 150 * @param documentId identifier of the document 151 * @return list of document category information 152 * @throws DoesNotExistException documentId not found 153 * @throws InvalidParameterException invalid documentId 154 * @throws MissingParameterException missing documentId 155 * @throws OperationFailedException unable to complete request 156 * @throws PermissionDeniedException authorization failure 157 */ 158 public List<DocumentCategoryInfo> getCategoriesByDocument(@WebParam(name="documentId")String documentId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 159 160 /** 161 * Retrieves information about a relationship between a reference and document. 162 * @param refDocRelationId reference document relationship identifier 163 * @return information about a relationship between a reference and a document 164 * @throws DoesNotExistException specified relationship not found 165 * @throws InvalidParameterException invalid refDocRelationId 166 * @throws MissingParameterException refDocRelationId not specified 167 * @throws OperationFailedException unable to complete request 168 * @throws PermissionDeniedException authorization failure 169 */ 170 public RefDocRelationInfo getRefDocRelation(@WebParam(name="refDocRelationId")String refDocRelationId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 171 172 /** 173 * Retrieves information about reference document relationships for a particular reference. 174 * @param refObjectTypeKey reference type 175 * @param refObjectId reference identifier 176 * @return list of reference document relationships 177 * @throws DoesNotExistException specified refId, refObjectTypeKey not found 178 * @throws InvalidParameterException invalid refId, refObjectTypeKey 179 * @throws MissingParameterException refId, refObjectTypeKey not specified 180 * @throws OperationFailedException unable to complete request 181 * @throws PermissionDeniedException authorization failure 182 */ 183 public List<RefDocRelationInfo> getRefDocRelationsByRef(@WebParam(name="refObjectTypeKey")String refObjectTypeKey, @WebParam(name="refObjectId")String refObjectId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 184 185 /** 186 * Retrieves information about reference document relationships for a particular document. 187 * @param documentId document identifier 188 * @return list of reference document relationships 189 * @throws DoesNotExistException specified document not found 190 * @throws InvalidParameterException invalid documentId 191 * @throws MissingParameterException documentId not specified 192 * @throws OperationFailedException unable to complete request 193 * @throws PermissionDeniedException authorization failure 194 */ 195 public List<RefDocRelationInfo> getRefDocRelationsByDoc(@WebParam(name="documentId")String documentId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 196 197 /** 198 * Validates a document. Depending on the value of validationType, this validation could be limited to tests on just the current object and its directly contained sub-objects or expanded to perform all tests related to this object. If an identifier is present for the document (and/or one of its contained sub-objects) and a record is found for that identifier, the validation checks if the document can be shifted to the new values. If an identifier is not present or a record cannot be found for the identifier, it is assumed that the record does not exist and as such, the checks performed will be much shallower, typically mimicking those performed by setting the validationType to the current object. 199 * @param validationType identifier of the extent of validation 200 * @param documentInfo document information to be tested. 201 * @return results from performing the validation 202 * @throws DoesNotExistException validationTypeKey not found 203 * @throws InvalidParameterException invalid validationTypeKey, documentInfo 204 * @throws MissingParameterException missing validationTypeKey, documentInfo 205 * @throws OperationFailedException unable to complete request 206 */ 207 public List<ValidationResultInfo> validateDocument(@WebParam(name="validationType")String validationType, @WebParam(name="documentInfo")DocumentInfo documentInfo) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException; 208 209 /** 210 * Creates a new document. 211 * @param documentTypeKey identifier of the document type 212 * @param documentCategoryKey identifier of the document category 213 * @param documentInfo detailed information on the document 214 * @return detailed information on the document created 215 * @throws DataValidationErrorException One or more values invalid for this operation 216 * @throws InvalidParameterException One or more parameters invalid 217 * @throws MissingParameterException One or more parameters missing 218 * @throws OperationFailedException unable to complete request 219 * @throws PermissionDeniedException authorization failure 220 */ 221 public DocumentInfo createDocument(@WebParam(name="documentTypeKey")String documentTypeKey, @WebParam(name="documentCategoryKey")String documentCategoryKey, @WebParam(name="documentInfo")DocumentInfo documentInfo) throws DataValidationErrorException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException, DoesNotExistException; 222 223 /** 224 * Updates an existing document. 225 * @param documentId identifier of the document to update 226 * @param documentInfo updated information for the document 227 * @return updated information on the document 228 * @throws DataValidationErrorException One or more values invalid for this operation 229 * @throws DoesNotExistException Document being updated does not exist 230 * @throws InvalidParameterException One or more parameters invalid 231 * @throws MissingParameterException One or more parameters missing 232 * @throws OperationFailedException unable to complete request 233 * @throws PermissionDeniedException authorization failure 234 * @throws VersionMismatchException The action was attempted on an out of date version. 235 */ 236 public DocumentInfo updateDocument(@WebParam(name="documentId")String documentId, @WebParam(name="documentInfo")DocumentInfo documentInfo) throws DataValidationErrorException, DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException, VersionMismatchException; 237 238 /** 239 * Deletes an existing document. 240 * @param documentId identifier of the document to delete 241 * @return status of the operation (success, failed) 242 * @throws DoesNotExistException Document to delete does not exist 243 * @throws InvalidParameterException One or more parameters invalid 244 * @throws MissingParameterException One or more parameters missing 245 * @throws OperationFailedException unable to complete request 246 * @throws PermissionDeniedException authorization failure 247 */ 248 public StatusInfo deleteDocument(@WebParam(name="documentId")String documentId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 249 250 /** 251 * Adds an existing document category to a document. 252 * @param documentId identifier of the document 253 * @param documentCategoryKey identifier of the document category 254 * @return status of the operation (success, failed) 255 * @throws DataValidationErrorException One or more values invalid for this operation 256 * @throws DoesNotExistException documentId, documentCategoryKey does not exist 257 * @throws InvalidParameterException one or more parameters invalid 258 * @throws MissingParameterException one or more parameters missing 259 * @throws OperationFailedException unable to complete request 260 * @throws PermissionDeniedException authorization failure 261 * @throws VersionMismatchException action was attempted on an out of date version. 262 */ 263 public StatusInfo addDocumentCategoryToDocument(@WebParam(name="documentId")String documentId, @WebParam(name="documentCategoryKey")String documentCategoryKey) throws DataValidationErrorException, DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException, VersionMismatchException; 264 265 /** 266 * Removes an existing category from a document. 267 * @param documentId identifier of the document 268 * @param documentCategoryKey identifier of the document category 269 * @return status of the operation (success, failed) 270 * @throws DoesNotExistException documentId, documentCategoryKey does not exist 271 * @throws InvalidParameterException One or more parameters invalid 272 * @throws MissingParameterException One or more parameters missing 273 * @throws OperationFailedException unable to complete request 274 * @throws PermissionDeniedException authorization failure 275 */ 276 public StatusInfo removeDocumentCategoryFromDocument(@WebParam(name="documentId")String documentId, @WebParam(name="documentCategoryKey")String documentCategoryKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 277 278 /** 279 * Validates a reference document relationship. Depending on the value of validationType, this validation could be limited to tests on just the current object and its directly contained sub-objects or expanded to perform all tests related to this object. If an identifier is present for the comment (and/or one of its contained sub-objects) and a record is found for that identifier, the validation checks if the comment can be shifted to the new values. If an identifier is not present or a record cannot be found for the identifier, it is assumed that the record does not exist and as such, the checks performed will be much shallower, typically mimicking those performed by setting the validationType to the current object. 280 * @param validationType identifier of the extent of validation 281 * @param refDocRelationInfo reference document relationship information to be tested. 282 * @return results from performing the validation 283 * @throws DoesNotExistException validationTypeKey not found 284 * @throws InvalidParameterException invalid validationTypeKey, refDocRelationInfo 285 * @throws MissingParameterException missing validationTypeKey, refDocRelationInfo 286 * @throws OperationFailedException unable to complete request 287 */ 288 public List<ValidationResultInfo> validateRefDocRelation(@WebParam(name="validationType")String validationType, @WebParam(name="refDocRelationInfo")RefDocRelationInfo refDocRelationInfo) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException; 289 290 /** 291 * Creates a relationship between a reference and a document. 292 * @param refObjectTypeKey reference type 293 * @param refObjectId identifier of the reference 294 * @param documentId identifier of the document 295 * @param refDocRelationTypeKey type of relationship between reference and document 296 * @param refDocRelationInfo detailed information about the reference/document relationship 297 * @return detailed information about the relationship 298 * @throws DataValidationErrorException One or more values invalid for this operation 299 * @throws InvalidParameterException One or more parameters invalid 300 * @throws MissingParameterException One or more parameters missing 301 * @throws OperationFailedException unable to complete request 302 * @throws PermissionDeniedException authorization failure 303 */ 304 public RefDocRelationInfo createRefDocRelation(@WebParam(name="refObjectTypeKey")String refObjectTypeKey, @WebParam(name="refObjectId")String refObjectId, @WebParam(name="documentId")String documentId, @WebParam(name="refDocRelationTypeKey")String refDocRelationTypeKey, @WebParam(name="refDocRelationInfo")RefDocRelationInfo refDocRelationInfo) throws DataValidationErrorException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 305 306 /** 307 * Updates a relationship between a reference and a document. 308 * @param refDocRelationId identifier of a relationship between a reference and document 309 * @param refDocRelationInfo detailed information about the relationship between a reference and document 310 * @return detailed information about the relationship between a reference and document 311 * @throws DataValidationErrorException One or more values invalid for this operation 312 * @throws InvalidParameterException One or more parameters invalid 313 * @throws MissingParameterException One or more parameters missing 314 * @throws OperationFailedException unable to complete request 315 * @throws PermissionDeniedException authorization failure 316 * @throws VersionMismatchException 317 * @throws DoesNotExistException 318 */ 319 public RefDocRelationInfo updateRefDocRelation(@WebParam(name="refDocRelationId")String refDocRelationId, @WebParam(name="refDocRelationInfo")RefDocRelationInfo refDocRelationInfo) throws DataValidationErrorException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException, VersionMismatchException, DoesNotExistException; 320 321 /** 322 * Removes a relationship between a reference and a document. 323 * @param refDocRelationId identifier of the relationship between the reference and document 324 * @return status of the operation (success, failed) 325 * @throws DoesNotExistException relationship does not exist 326 * @throws InvalidParameterException One or more parameters invalid 327 * @throws MissingParameterException One or more parameters missing 328 * @throws OperationFailedException unable to complete request 329 * @throws PermissionDeniedException authorization failure 330 */ 331 public StatusInfo deleteRefDocRelation(@WebParam(name="refDocRelationId")String refDocRelationId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 332 333 }