001/**
002 * Copyright 2005-2016 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.ksb.api.bus;
017
018import java.net.URL;
019
020import javax.xml.namespace.QName;
021
022import org.kuali.rice.core.api.config.ConfigurationException;
023import org.kuali.rice.core.api.security.credentials.CredentialsType;
024import org.kuali.rice.ksb.api.registry.ServiceRegistry;
025
026
027
028/**
029 * Defines the common parameters for the publication and export of a service
030 * to the {@link ServiceBus} and {@link ServiceRegistry}.  Implementations of
031 * this interface may define additional properties that are required for the
032 * publication of services of that particular type.
033 * 
034 * @author Kuali Rice Team (rice.collab@kuali.org)
035 */
036public interface ServiceDefinition {
037        
038        /**
039         * Validates the service definition after creation of the service definition.
040         * It's intended that portions of the KSB that handle publication and export
041         * of services to the bus will execute this prior to successful export of
042         * the service.
043         * 
044         * @throws ConfigurationException if this service definition is not
045         * configured properly
046         */
047        void validate();
048
049        /**
050         * Establishes and returns an {@link Endpoint} to this service which
051         * generates the {@link ServiceConfiguration} for this service definition
052         * as well as including the actual service implementation as provided by
053         * {@link #getService()}.
054         * 
055         * <p>The {@link #validate()} method should be invoked prior to executing
056         * this method in order to ensure that the appropriate internal state for
057         * the {@link ServiceDefinition} has been established.
058         * 
059         * @return the established endpoint, should never return null
060         */
061        Endpoint establishEndpoint();
062        
063        /**
064         * Return the actual service implementation to publish and export to the
065         * service bus.
066         * 
067         * @return the service to publish
068         */
069        Object getService();
070        
071        /**
072         * Returns the qualified name for this service.
073         * 
074         * @return the qualified name for this service
075         */
076        QName getServiceName();
077        
078        /**
079         * Returns the URL of the endpoint which provides this service.
080         * 
081         * @return the endpoint URL of the service
082         */
083        URL getEndpointUrl();
084        
085        /**
086         * Returns the {@link ClassLoader} that should be set as the context
087         * classloader on the thread prior to any invocations on the service
088         * 
089         * @return the classloader for this service
090         */
091        ClassLoader getServiceClassLoader();
092        
093        /**
094         * Returns the url path to export the service under.
095         * 
096         * @return the url path to export the service under
097         */
098        String getServicePath();
099
100    /**
101         * Returns the id of the specific instance of the application which owns this service
102         *
103         * @return the id of the specific instance of the application which owns this service
104         */
105        String getInstanceId();
106
107        /**
108         * Returns the id of the application which owns this service.
109         * 
110         * @return the id of the application which owns this service
111         */
112        String getApplicationId();
113
114        /**
115         * Returns the version of this service.
116         * 
117         * @return the version of this service
118         */
119        String getServiceVersion();
120        
121        /**
122         * Returns the type of this service.
123         * 
124         * @return the type of this service
125         */
126        String getType();
127        
128        /**
129         * Return true if this service uses queue-style messaging, false if it uses
130         * topic-style messaging.
131         * 
132         * @return true if this service uses queue-style messaging, false if it uses
133         * topic-style messaging
134         */
135        boolean isQueue();
136        
137        /**
138         * Returns the processing priority for messages that are sent to this service.
139         * 
140         * @return the message processing priority for this service
141         */
142        Integer getPriority();
143        
144        /**
145         * Returns the retry attempts to use when processing messages sent to this
146         * service.
147         * 
148         * @return the retry attempts for this service
149         */
150        Integer getRetryAttempts();
151        
152        /**
153         * Returns the maximum amount of milliseconds a message to this service can
154         * live and attempt to be processed successfully by this service before it's
155         * forced into processing by it's exception handler.
156         *  
157         * @return the maximum lifetime for this message, if null then this message has
158         * an infinite lifetime
159         */
160        Long getMillisToLive();
161        
162        /**
163         * Returns the name of the exception handler to invoke whenever messages to
164         * this service fail to be sent.  If null, the default message exception
165         * handler will be used.
166         * 
167         * @return the name of the message exception handler for this service, or
168         * null if the default handler should be used
169         */
170        String getMessageExceptionHandler();
171        
172        /**
173         * Returns true if this service is secured by standard KSB security features.
174         * 
175         * @return true if this service is secured, false otherwise
176         */
177        Boolean getBusSecurity();
178        
179        /**
180         * Returns the type of security credentials that should be used when
181         * attempting to authorize access to this service.
182         * 
183         * @return the type of security credentials to use when access this service
184         */
185        CredentialsType getCredentialsType();
186
187        /**
188         * Returns whether the service is secured with basic authentication
189         *
190         * @return true if this service is secured with basic authentication
191         */
192        boolean isBasicAuthentication();
193}