001 /**
002 * Copyright 2005-2012 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.ksb.api.bus;
017
018 import java.net.URL;
019
020 import javax.xml.namespace.QName;
021
022 import org.kuali.rice.core.api.config.ConfigurationException;
023 import org.kuali.rice.core.api.security.credentials.CredentialsType;
024 import 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 */
036 public 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 }