Source code: org/apache/axis/EngineConfiguration.java
1 /*
2 * Copyright 2002-2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache 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.apache.org/licenses/LICENSE-2.0
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
17 package org.apache.axis;
18
19 import org.apache.axis.encoding.TypeMappingRegistry;
20 import org.apache.axis.handlers.soap.SOAPService;
21
22 import javax.xml.namespace.QName;
23 import java.util.Hashtable;
24 import java.util.Iterator;
25 import java.util.List;
26
27 /**
28 * EngineConfiguration is an interface that the Message Flow subsystem
29 * provides so that engine configuration can be provided in a pluggable
30 * way. An instance of EngineConfiguration provides configuration
31 * for a particular engine instance.
32 * <p>
33 * Concrete implementations of this interface will obtain configuration
34 * information from some source (examples might be files, Strings, or
35 * databases) and are responsible for writing it into an AxisEngine, and
36 * writing an AxisEngine's state back out to whatever storage medium is in use.
37 *
38 * @author Glyn Normington (glyn@apache.org)
39 * @author Glen Daniels (gdaniels@apache.org)
40 */
41 public interface EngineConfiguration {
42 /**
43 * Property name used for setting an EngineConfiguration to be used
44 * in creating engines.
45 */
46 static final String PROPERTY_NAME = "engineConfig";
47
48 /**
49 * Configure this AxisEngine using whatever data source we have.
50 *
51 * @param engine the AxisEngine we'll deploy state to
52 * @throws ConfigurationException if there was a problem
53 */
54 void configureEngine(AxisEngine engine) throws ConfigurationException;
55
56 /**
57 * Read the configuration from an engine, and store it somehow.
58 *
59 * @param engine the AxisEngine from which to read state.
60 * @throws ConfigurationException if there was a problem
61 */
62 void writeEngineConfig(AxisEngine engine) throws ConfigurationException;
63
64 // fixme: if no handler is found, do we return null, or throw a
65 // ConfigurationException, or throw another exception? IMHO returning
66 // null is nearly always evil
67 /**
68 * Retrieve an instance of the named handler.
69 *
70 * @param qname the <code>QName</code> identifying the
71 * <code>Handler</code>
72 * @return the <code>Handler</code> associated with <code>qname</code>
73 * @throws ConfigurationException if there was a failure in resolving
74 * <code>qname</code>
75 */
76 Handler getHandler(QName qname) throws ConfigurationException;
77
78 /**
79 * Retrieve an instance of the named service.
80 *
81 * @param qname the <code>QName</code> identifying the
82 * <code>Service</code>
83 * @return the <code>Service</code> associated with <code>qname</code>
84 * @throws ConfigurationException if there was an error resolving the
85 * qname
86 */
87 SOAPService getService(QName qname) throws ConfigurationException;
88
89 /**
90 * Get a service which has been mapped to a particular namespace.
91 *
92 * @param namespace a namespace URI
93 * @return an instance of the appropriate Service, or null
94 * @throws ConfigurationException if there was an error resolving the
95 * namespace
96 */
97 SOAPService getServiceByNamespaceURI(String namespace)
98 throws ConfigurationException;
99
100 /**
101 * Retrieve an instance of the named transport.
102 *
103 * @param qname the <code>QName</code> of the transport
104 * @return a <code>Handler</code> implementing the transport
105 * @throws ConfigurationException if there was an error resolving the
106 * transport
107 */
108 Handler getTransport(QName qname) throws ConfigurationException;
109
110 /**
111 * Retrieve the TypeMappingRegistry for this engine.
112 *
113 * @return the type mapping registry
114 * @throws ConfigurationException if there was an error resolving the
115 * registry
116 */
117 TypeMappingRegistry getTypeMappingRegistry()
118 throws ConfigurationException;
119
120 /**
121 * Returns a global request handler.
122 *
123 * @return the <code>Handler</code> that globally handles requests
124 * @throws ConfigurationException if there was some error fetching the
125 * handler
126 */
127 Handler getGlobalRequest() throws ConfigurationException;
128
129 /**
130 * Returns a global response handler.
131 *
132 * @return the <code>Handler</code> that globally handles responses
133 * @throws ConfigurationException if there was some error fetching the
134 * handler
135 */
136 Handler getGlobalResponse() throws ConfigurationException;
137
138 // fixme: where is the contract for what can be in this Hashtable?
139 // fixme: did we intend to use Hashtable? Will Map do? Do we need
140 // synchronization? If so, will one of the Collections synchronized
141 // wrappers do fine?
142 /**
143 * Returns the global configuration options.
144 *
145 * @return the global options as a <code>Hashtable</code>
146 * @throws ConfigurationException if the global options could not be
147 * returned
148 */
149 Hashtable getGlobalOptions() throws ConfigurationException;
150
151 /**
152 * Get an enumeration of the services deployed to this engine.
153 * Each service is represented as <code>ServiceDesc</code> object.
154 *
155 * @see org.apache.axis.description.ServiceDesc
156 * @return an <code>Iterator</code> over the <code>ServiceDesc</code>
157 * objects
158 * @throws ConfigurationException if the deployed services could not be
159 * returned
160 */
161 Iterator getDeployedServices() throws ConfigurationException;
162
163 /**
164 * Get a list of roles that this engine plays globally. Services
165 * within the engine configuration may also add additional roles.
166 *
167 * @return a <code>List</code> of the roles for this engine
168 */
169 List getRoles();
170 }