1 /*
2 * Copyright 2006-2011 The Kuali Foundation
3 *
4 * Licensed under the Educational Community 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.opensource.org/licenses/ecl2.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
17 package org.kuali.rice.shareddata.api.state;
18
19 import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
20 import org.kuali.rice.core.util.jaxb.ImmutableListAdapter;
21 import org.kuali.rice.shareddata.api.SharedDataConstants;
22
23 import javax.jws.WebMethod;
24 import javax.jws.WebParam;
25 import javax.jws.WebResult;
26 import javax.jws.WebService;
27 import javax.jws.soap.SOAPBinding;
28 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
29 import java.util.List;
30
31 /**
32 * Service for interacting with {@link State States}.
33 */
34 @WebService(name = "StateService", targetNamespace = SharedDataConstants.Namespaces.SHAREDDATA_NAMESPACE)
35 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
36 public interface StateService {
37
38 /**
39 * Gets a {@link State} from a postal country code and postal state code.
40 * <p/>
41 * <p>
42 * This method will return null if the state does not exist.
43 * </p>
44 * <p/>
45 * <p>
46 * This method will return active or inactive states.
47 * </p>
48 *
49 * @param countryCode country code. cannot be blank.
50 * @param code state code. cannot be blank.
51 * @return a {@link State} or null
52 * @throws IllegalArgumentException country code or state code is blank
53 */
54 @WebMethod(operationName = "getState")
55 @WebResult(name = "state")
56 State getState(@WebParam(name = "countryCode") String countryCode, @WebParam(name = "code") String code)
57 throws RiceIllegalArgumentException;
58
59 /**
60 * Finds all the {@link State States} for postal country code.
61 * <p/>
62 * <p>
63 * This method will always return an <b>immutable</b> Collection
64 * even when no values exist.
65 * </p>
66 * <p/>
67 * <p>
68 * This method will only return active states.
69 * </p>
70 *
71 * @param countryCode state code. cannot be blank.
72 * @return an immutable collection of states
73 * @throws IllegalArgumentException country code is blank
74 */
75 @WebMethod(operationName = "findAllStatesInCountry")
76 @WebResult(name = "states")
77 @XmlJavaTypeAdapter(ImmutableListAdapter.class)
78 List<State> findAllStatesInCountry(@WebParam(name = "countryCode") String countryCode)
79 throws RiceIllegalArgumentException;
80 }