1 /**
2 * Copyright 2005-2011 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.ksb.api.bus;
17
18 import java.net.URL;
19
20 import javax.xml.namespace.QName;
21
22 import org.kuali.rice.core.api.config.ConfigurationException;
23 import org.kuali.rice.core.api.security.credentials.CredentialsType;
24 import org.kuali.rice.ksb.api.registry.ServiceRegistry;
25
26
27
28 /**
29 * Defines the common parameters for the publication and export of a service
30 * to the {@link ServiceBus} and {@link ServiceRegistry}. Implementations of
31 * this interface may define additional properties that are required for the
32 * publication of services of that particular type.
33 *
34 * @author Kuali Rice Team (rice.collab@kuali.org)
35 */
36 public interface ServiceDefinition {
37
38 /**
39 * Validates the service definition after creation of the service definition.
40 * It's intended that portions of the KSB that handle publication and export
41 * of services to the bus will execute this prior to successful export of
42 * the service.
43 *
44 * @throws ConfigurationException if this service definition is not
45 * configured properly
46 */
47 void validate();
48
49 /**
50 * Establishes and returns an {@link Endpoint} to this service which
51 * generates the {@link ServiceConfiguration} for this service definition
52 * as well as including the actual service implementation as provided by
53 * {@link #getService()}.
54 *
55 * <p>The {@link #validate()} method should be invoked prior to executing
56 * this method in order to ensure that the appropriate internal state for
57 * the {@link ServiceDefinition} has been established.
58 *
59 * @return the established endpoint, should never return null
60 */
61 Endpoint establishEndpoint();
62
63 /**
64 * Return the actual service implementation to publish and export to the
65 * service bus.
66 *
67 * @return the service to publish
68 */
69 Object getService();
70
71 /**
72 * Returns the qualified name for this service.
73 *
74 * @return the qualified name for this service
75 */
76 QName getServiceName();
77
78 /**
79 * Returns the URL of the endpoint which provides this service.
80 *
81 * @return the endpoint URL of the service
82 */
83 URL getEndpointUrl();
84
85 /**
86 * Returns the {@link ClassLoader} that should be set as the context
87 * classloader on the thread prior to any invocations on the service
88 *
89 * @return the classloader for this service
90 */
91 ClassLoader getServiceClassLoader();
92
93 /**
94 * Returns the url path to export the service under.
95 *
96 * @return the url path to export the service under
97 */
98 String getServicePath();
99
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 the name of the cache manager to use. If null or blank then caching is effectively
189 * disabled for this service.
190 *
191 * @return the cache manager name or null
192 */
193 String getCacheManager();
194
195 }