001 /**
002 * Copyright 2005-2013 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.kuali.rice.location.api.country;
017
018 import org.kuali.rice.core.api.criteria.QueryByCriteria;
019 import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
020 import org.kuali.rice.core.api.exception.RiceIllegalStateException;
021 import org.kuali.rice.location.api.LocationConstants;
022 import org.springframework.cache.annotation.Cacheable;
023
024 import javax.jws.WebMethod;
025 import javax.jws.WebParam;
026 import javax.jws.WebResult;
027 import javax.jws.WebService;
028 import javax.jws.soap.SOAPBinding;
029 import javax.xml.bind.annotation.XmlElement;
030 import javax.xml.bind.annotation.XmlElementWrapper;
031 import java.util.List;
032
033
034 /**
035 * <p>CountryService interface.</p>
036 *
037 * @author Kuali Rice Team (rice.collab@kuali.org)
038 */
039 @WebService(name = "CountryService", targetNamespace = LocationConstants.Namespaces.LOCATION_NAMESPACE_2_0)
040 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
041 public interface CountryService {
042
043 /**
044 * Lookup a country object based on the given country code.
045 *
046 * @param code the given country code
047 * @return a country object with the given country code. A null reference is returned if an invalid or
048 * non-existant code is supplied.
049 * @throws RiceIllegalArgumentException if the code is blank or null
050 */
051 @WebMethod(operationName = "getCountry")
052 @WebResult(name = "country")
053 @Cacheable(value=Country.Cache.NAME, key="'code=' + #p0")
054 Country getCountry(@WebParam(name = "code") String code) throws RiceIllegalArgumentException;
055
056 /**
057 * Get a country object based on an alternate country code
058 *
059 * @param alternateCode the given alternate country code
060 * @return A country object with the given alternate country code if a country with that alternate country code
061 * exists. Otherwise, null is returned.
062 * @throws RiceIllegalStateException if multiple Countries exist with the same passed in alternateCode
063 * @throws RiceIllegalArgumentException if alternateCode is null or is a whitespace only string.
064 */
065 @WebMethod(operationName = "getCountryByAlternateCode")
066 @WebResult(name = "country")
067 @Cacheable(value=Country.Cache.NAME, key="'alternateCode=' + #p0")
068 Country getCountryByAlternateCode(@WebParam(name = "alternateCode") String alternateCode)
069 throws RiceIllegalStateException, RiceIllegalArgumentException;
070
071 /**
072 * Returns all Countries that are not restricted.
073 *
074 * @return all countries that are not restricted
075 */
076 @WebMethod(operationName = "findAllCountriesNotRestricted")
077 @XmlElementWrapper(name = "countriesNotRestricted", required = false)
078 @XmlElement(name = "countryNotRestricted", required = false)
079 @WebResult(name = "countriesNotRestricted")
080 @Cacheable(value=Country.Cache.NAME, key="'allRestricted'")
081 List<Country> findAllCountriesNotRestricted();
082
083 /**
084 * Returns all Countries
085 *
086 * @return all countries
087 */
088 @WebMethod(operationName = "findAllCountries")
089 @XmlElementWrapper(name = "countries", required = false)
090 @XmlElement(name = "country", required = false)
091 @WebResult(name = "countries")
092 @Cacheable(value=Country.Cache.NAME, key="'all'")
093 List<Country> findAllCountries();
094
095 /**
096 * Returns the system default country. This is simply meant to be informational for applications which need the
097 * ability to utilize a default country (such as for defaulting of certain fields during data entry). This method
098 * may return null in situations where no default country is configured.
099 *
100 * @return the default country, or null if no default country is defined
101 */
102 @WebMethod(operationName = "getDefaultCountry")
103 @WebResult(name = "country")
104 @Cacheable(value = Country.Cache.NAME, key="'default'")
105 Country getDefaultCountry();
106
107 /**
108 * This method find Countries based on a query criteria. The criteria cannot be null.
109 *
110 * @since 2.0.1
111 * @param queryByCriteria the criteria. Cannot be null.
112 * @return query results. will never return null.
113 * @throws IllegalArgumentException if the queryByCriteria is null
114 */
115 @WebMethod(operationName = "findCountries")
116 @WebResult(name = "results")
117 CountryQueryResults findCountries(@WebParam(name = "query") QueryByCriteria queryByCriteria) throws RiceIllegalArgumentException;
118
119 }