001/**
002 * Copyright 2005-2015 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 */
016package org.kuali.rice.location.api.country;
017
018import org.kuali.rice.core.api.criteria.QueryByCriteria;
019import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
020import org.kuali.rice.core.api.exception.RiceIllegalStateException;
021import org.kuali.rice.location.api.LocationConstants;
022import org.springframework.cache.annotation.Cacheable;
023
024import javax.jws.WebMethod;
025import javax.jws.WebParam;
026import javax.jws.WebResult;
027import javax.jws.WebService;
028import javax.jws.soap.SOAPBinding;
029import javax.xml.bind.annotation.XmlElement;
030import javax.xml.bind.annotation.XmlElementWrapper;
031import 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)
041public 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}