1 /** 2 * Copyright 2010 The Kuali Foundation Licensed under the 3 * Educational Community License, Version 2.0 (the "License"); you may 4 * not use this file except in compliance with the License. You may 5 * obtain a copy of the License at 6 * 7 * http://www.osedu.org/licenses/ECL-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, 10 * software distributed under the License is distributed on an "AS IS" 11 * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 12 * or implied. See the License for the specific language governing 13 * permissions and limitations under the License. 14 */ 15 16 package org.kuali.student.core.enumerationmanagement.service; 17 18 import java.util.Date; 19 import java.util.List; 20 21 import javax.jws.WebParam; 22 import javax.jws.WebService; 23 import javax.jws.soap.SOAPBinding; 24 25 import org.kuali.student.core.dictionary.service.DictionaryService; 26 import org.kuali.student.core.dto.StatusInfo; 27 import org.kuali.student.core.enumerationmanagement.dto.EnumeratedValueInfo; 28 import org.kuali.student.core.enumerationmanagement.dto.EnumerationInfo; 29 import org.kuali.student.core.exceptions.AlreadyExistsException; 30 import org.kuali.student.core.exceptions.DoesNotExistException; 31 import org.kuali.student.core.exceptions.InvalidParameterException; 32 import org.kuali.student.core.exceptions.MissingParameterException; 33 import org.kuali.student.core.exceptions.OperationFailedException; 34 import org.kuali.student.core.exceptions.PermissionDeniedException; 35 import org.kuali.student.core.search.service.SearchService; 36 37 @WebService(name = "EnumerationManagementService", targetNamespace = "http://student.kuali.org/wsdl/enumerationmanagement") 38 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED) 39 public interface EnumerationManagementService extends DictionaryService, SearchService { 40 41 /** 42 * Retrieves the list of meta information for the enumerations supported by 43 * this service. 44 * 45 * @return list of enumeration meta information 46 * @throws OperationFailedException 47 * unable to complete request 48 */ 49 public List<EnumerationInfo> getEnumerations() 50 throws OperationFailedException; 51 52 /** 53 * Retrieves meta information for a particular Enumeration. The meta 54 * information should describe constraints on the various fields comprising 55 * the enumeration as well as the allowed contexts. 56 * 57 * @param enumerationKey 58 * Identifier for the Enumeration 59 * @return Meta information about an enumeration 60 * @throws DoesNotExistException 61 * enumerationKey not found 62 * @throws InvalidParameterException 63 * invalid enumerationKey 64 * @throws MissingParameterException 65 * missing enumerationKey 66 * @throws OperationFailedException 67 * unable to complete request 68 */ 69 public EnumerationInfo getEnumeration( 70 @WebParam(name = "enumerationKey") String enumerationKey) 71 throws DoesNotExistException, InvalidParameterException, 72 MissingParameterException, OperationFailedException; 73 74 /** 75 * Retrieves the list of values for a particular enumeration with a certain 76 * context for a particular date. The values returned should be those where 77 * the supplied date is between the effective and expiration dates. Certain 78 * enumerations may not support this functionality. 79 * 80 * @param enumerationKey 81 * Identifier for the Enumeration 82 * @param contextType 83 * Identifier for the enumeration context type 84 * @param contextValue 85 * Value for the enumeration context 86 * @param contextDate 87 * date and time to get the enumeration for 88 * @return list of Codes and Values 89 * @throws DoesNotExistException 90 * enumerationKey not found 91 * @throws InvalidParameterException 92 * invalid enumerationKey, contextKey, contextValue, contextDate 93 * @throws MissingParameterException 94 * missing enumerationKey, contextKey, contextValue, contextDate 95 * @throws OperationFailedException 96 * unable to complete request 97 */ 98 public List<EnumeratedValueInfo> getEnumeratedValues( 99 @WebParam(name = "enumerationKey") String enumerationKey, 100 @WebParam(name = "contextKey") String contextKey, 101 @WebParam(name = "contextValue") String contextValue, 102 @WebParam(name = "contextDate") Date contextDate) 103 throws DoesNotExistException, InvalidParameterException, 104 MissingParameterException, OperationFailedException; 105 106 /** 107 * Adds an value to a particular Enumeration. 108 * 109 * @param enumerationKey 110 * Identifier for the Enumeration 111 * @param enumeratedValue 112 * Value to be added 113 * @return newly created enumerated value 114 * @throws AlreadyExistsException 115 * enumerated value already exists 116 * @throws InvalidParameterException 117 * invalid enumerationKey, code, enumeratedValue 118 * @throws MissingParameterException 119 * missing enumerationKey, code, enumeratedValue 120 * @throws OperationFailedException 121 * unable to complete request 122 * @throws PermissionDeniedException 123 * authorization failure 124 */ 125 public EnumeratedValueInfo addEnumeratedValue( 126 @WebParam(name = "enumerationKey") String enumerationKey, 127 @WebParam(name = "enumeratedValue") EnumeratedValueInfo enumeratedValue) 128 throws AlreadyExistsException, InvalidParameterException, 129 MissingParameterException, OperationFailedException, 130 PermissionDeniedException; 131 132 /** 133 * Updates a value in a particular Enumeration. The pattern in this 134 * signature is different from most updates in that it is unlikely for 135 * multiple individuals or processes to be altering the same construct at 136 * the same time. 137 * 138 * @param enumerationKey 139 * Identifier for the Enumeration 140 * @param code 141 * code identifying the value to be updated 142 * @param enumeratedValue 143 * updated information on the value 144 * @return updated enumerated value 145 * @throws DoesNotExistException 146 * enumerationKey, code not found 147 * @throws InvalidParameterException 148 * invalid enumerationKey, enumeratedValue 149 * @throws MissingParameterException 150 * missing enumerationKey, enumeratedValue 151 * @throws OperationFailedException 152 * unable to complete request 153 * @throws PermissionDeniedException 154 * authorization failure 155 */ 156 public EnumeratedValueInfo updateEnumeratedValue( 157 @WebParam(name = "enumerationKey") String enumerationKey, 158 @WebParam(name = "code") String code, 159 @WebParam(name = "enumeratedValue") EnumeratedValueInfo enumeratedValue) 160 throws DoesNotExistException, InvalidParameterException, 161 MissingParameterException, OperationFailedException, 162 PermissionDeniedException; 163 164 /** 165 * Removes a value from a particular Enumeration. This particular operation 166 * should be used sparingly, as removal of a value may lead to dangling 167 * references. It is suggested that standard procedure should be to update 168 * the expiration date for the value so that it is seen as expired. 169 * 170 * @param enumerationKey 171 * Identifier for the Enumeration 172 * @param code 173 * code identifying the value to be removed 174 * @return status of the operation 175 * @throws DoesNotExistException 176 * enumerationKey, code not found 177 * @throws InvalidParameterException 178 * invalid enumerationKey, enumeratedValue 179 * @throws MissingParameterException 180 * missing enumerationKey, enumeratedValue 181 * @throws OperationFailedException 182 * unable to complete request 183 * @throws PermissionDeniedException 184 * authorization failure 185 */ 186 public StatusInfo removeEnumeratedValue( 187 @WebParam(name = "enumerationKey") String enumerationKey, 188 @WebParam(name = "code") String code) throws DoesNotExistException, 189 InvalidParameterException, MissingParameterException, 190 OperationFailedException, PermissionDeniedException; 191 192 }