1 /** 2 * Copyright 2005-2012 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 package org.kuali.rice.coreservice.api.component; 17 18 import org.kuali.rice.core.api.CoreConstants; 19 import org.kuali.rice.core.api.exception.RiceIllegalArgumentException; 20 21 import javax.jws.WebMethod; 22 import javax.jws.WebParam; 23 import javax.jws.WebResult; 24 import javax.jws.WebService; 25 import javax.jws.soap.SOAPBinding; 26 import javax.xml.bind.annotation.XmlElement; 27 import javax.xml.bind.annotation.XmlElementWrapper; 28 import java.util.List; 29 30 /** 31 * Defines the contract for a service which can be used to interact with the Rice core component store. 32 * 33 * @author Kuali Rice Team (rice.collab@kuali.org) 34 */ 35 @WebService(name = "componentService", targetNamespace = CoreConstants.Namespaces.CORE_NAMESPACE_2_0) 36 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED) 37 public interface ComponentService { 38 39 40 /** 41 * This will return a {@link org.kuali.rice.coreservice.api.component.Component} with the given namespaceCode and 42 * componentCode 43 * 44 * @param namespaceCode the namespaceCode of the component 45 * @param componentCode the componentCode of the component 46 * @return the component with the given namespaceCode and componentCode 47 * @throws RiceIllegalArgumentException if the namespaceCode or componentCode is null or blank 48 */ 49 @WebMethod(operationName = "getComponentByCode") 50 @WebResult(name = "component") 51 Component getComponentByCode( 52 @WebParam(name = "namespaceCode") String namespaceCode, 53 @WebParam(name = "componentCode") String componentCode 54 ) throws RiceIllegalArgumentException; 55 56 57 /** 58 * This will return a list of all {@link org.kuali.rice.coreservice.api.component.Component} with the 59 * given namespaceCode 60 * 61 * @param namespaceCode the namespaceCode of the component 62 * @return a list of components with the given namespaceCode 63 * @throws RiceIllegalArgumentException if the namespaceCode is null or blank 64 */ 65 @WebMethod(operationName = "getAllComponentsByNamespaceCode") 66 @WebResult(name = "components") 67 @XmlElementWrapper(name = "components", required = true) 68 @XmlElement(name = "component", required = false) 69 List<Component> getAllComponentsByNamespaceCode( 70 @WebParam(name = "namespaceCode") String namespaceCode 71 ) throws RiceIllegalArgumentException; 72 73 74 /** 75 * This will return a list of active {@link org.kuali.rice.coreservice.api.component.Component} with the 76 * given namespaceCode 77 * 78 * @param namespaceCode the namespaceCode of the component 79 * @return a list of active components with the given namespaceCode 80 * @throws RiceIllegalArgumentException if the namespaceCode is null or blank 81 */ 82 @WebMethod(operationName = "getActiveComponentsByNamespaceCode") 83 @WebResult(name = "components") 84 @XmlElementWrapper(name = "components", required = true) 85 @XmlElement(name = "component", required = false) 86 List<Component> getActiveComponentsByNamespaceCode( 87 @WebParam(name = "namespaceCode") String namespaceCode 88 ) throws RiceIllegalArgumentException; 89 90 91 /** 92 * This will return a list of derived {@link org.kuali.rice.coreservice.api.component.Component} with the 93 * given componentSetId 94 * 95 * @param componentSetId the componentSetId of the component 96 * @return a list of components with the given componentSetId 97 * @throws RiceIllegalArgumentException if the componentSetId is null or blank 98 */ 99 @WebMethod(operationName = "getDerivedComponentSet") 100 @WebResult(name = "components") 101 @XmlElementWrapper(name = "components", required = true) 102 @XmlElement(name = "component", required = false) 103 List<Component> getDerivedComponentSet(@WebParam(name = "componentSetId") String componentSetId) throws RiceIllegalArgumentException; 104 105 /** 106 * Publishes the given set of derived components to make them available to the component system. It should only 107 * ever be necessary to invoke this service whenever published components for an application change. However, it is 108 * always safe to invoke this method even if the client cannot make this determination as the implementation of this 109 * service should be responsible for handling the given information and ignoring it if no publication needs to 110 * occur. To this end, this method should be idempotent. 111 * 112 * <p>When invoked, the set of components known to the component system for the given component set id will be 113 * replaced with the given list. Any previously published components for the component set id which are not 114 * contained within the given list will be deleted.</p> 115 * 116 * <p>The {@code componentSetId} should be an identifier generated by the client application which uniquely 117 * identifies the component set being published (either newly published or updated). A simple value to use would 118 * be the {@code applicationId} of the client application but this would mean an application could only ever publish 119 * a single custom component set. So the {@code applicationId} could also be combined with some additional 120 * information on the source of the components being published if a particular application needs to publish custom 121 * components from multiple sources.</p> 122 * 123 * <p>The {@code componentSetId} on each of the components supplied in the list must either be null or equal to the 124 * component set id that is passed to this method, otherwise a {@code RiceIllegalArgumentException} will be thrown.</p> 125 * 126 * @param componentSetId an id that uniquely identifies this set of components being checked. The service will use 127 * this to track the components being published 128 * @param components the components to publish, may be empty or null, in which case all published components for the 129 * given component set id will be deleted from the component system if any exist 130 * 131 * @throws RiceIllegalArgumentException if componentSetId is a null or blank value 132 * @throws RiceIllegalArgumentException if any of the components in the given list have a non-null componentSetId 133 * which does not match the componentSetId parameter supplied to this method 134 */ 135 @WebMethod(operationName = "publishDerivedComponents") 136 void publishDerivedComponents(@WebParam(name = "componentSetId") String componentSetId, 137 @WebParam(name = "components") List<Component> components) throws RiceIllegalArgumentException; 138 139 }