Debian Codegraph @

src/java/org/astrogrid/samp/xmlrpc/XmlRpcKit.java

raw
1 package org.astrogrid.samp.xmlrpc;
2
3 import java.lang.reflect.Field;
4 import java.lang.reflect.Modifier;
5 import java.util.logging.Logger;
6
7 /**
8 * Encapsulates the provision of XML-RPC client and server capabilities.
9 * Two implementations are provided in the JSAMP package;
10 * the pluggable architecture allows others to be provided.
11 *
12 * @author Mark Taylor
13 * @since 27 Aug 2008
14 */
15 public abstract class XmlRpcKit {
16
17 /** Implementation based on Apache XML-RPC. */
18 public static final XmlRpcKit APACHE;
19
20 /** Implementation which requires no external libraries. */
21 public static final XmlRpcKit INTERNAL;
22
23 /** Internal implementation variant with verbose logging of XML I/O. */
24 public static final XmlRpcKit XML_LOGGING;
25
26 /** Internal implementation variant with verbose logging of RPC calls. */
27 public static final XmlRpcKit RPC_LOGGING;
28
29 /** Array of available known implementations of this class. */
30 public static XmlRpcKit[] KNOWN_IMPLS = {
31 INTERNAL = createReflectionKit(
32 "internal",
33 "org.astrogrid.samp.xmlrpc.internal.InternalClientFactory",
34 "org.astrogrid.samp.xmlrpc.internal.InternalServerFactory" ),
35 XML_LOGGING = createReflectionKit(
36 "xml-log",
37 "org.astrogrid.samp.xmlrpc.internal"
38 + ".XmlLoggingInternalClientFactory",
39 "org.astrogrid.samp.xmlrpc.internal"
40 + ".XmlLoggingInternalServerFactory" ),
41 RPC_LOGGING = createReflectionKit(
42 "rpc-log",
43 "org.astrogrid.samp.xmlrpc.internal"
44 + ".RpcLoggingInternalClientFactory",
45 "org.astrogrid.samp.xmlrpc.internal"
46 + ".RpcLoggingInternalServerFactory" ),
47 APACHE = createApacheKit( "apache" ),
48 };
49
50 /**
51 * Property which is examined to determine which implementation to use
52 * by default. Property values may be one of the elements of
53 * {@link #KNOWN_IMPLS}, currently:
54 * <ul>
55 * <li>internal</li>
56 * <li>xml-log</li>
57 * <li>rpc-log</li>
58 * <li>apache</li>
59 * </ul>
60 * Alternatively, it may be the classname of a class which implements
61 * {@link org.astrogrid.samp.xmlrpc.XmlRpcKit}
62 * and has a no-arg constructor.
63 * The property name is {@value}.
64 */
65 public static final String IMPL_PROP = "jsamp.xmlrpc.impl";
66
67 private static XmlRpcKit defaultInstance_;
68 private static Logger logger_ =
69 Logger.getLogger( XmlRpcKit.class.getName() );
70
71 /**
72 * Returns an XML-RPC client factory.
73 *
74 * @return client factory
75 */
76 public abstract SampXmlRpcClientFactory getClientFactory();
77
78 /**
79 * Returns an XML-RPC server factory.
80 *
81 * @return server factory
82 */
83 public abstract SampXmlRpcServerFactory getServerFactory();
84
85 /**
86 * Indicates whether this object is ready for use.
87 * If it returns false (perhaps because some classes are unavailable
88 * at runtime) then {@link #getClientFactory} and {@link #getServerFactory}
89 * may throw exceptions rather than behaving as documented.
90 *
91 * @return true if this object works
92 */
93 public abstract boolean isAvailable();
94
95 /**
96 * Returns the name of this kit.
97 *
98 * @return implementation name
99 */
100 public abstract String getName();
101
102 /**
103 * Returns the default instance of this class.
104 * What implementation this is normally depends on what classes
105 * are present at runtime.
106 * However, if the system property {@link #IMPL_PROP} is set this
107 * will determine the implementation used. It may be one of:
108 * <ul>
109 * <li><code>apache</code>: implementation based on the
110 * Apache XML-RPC library</li>
111 * <li><code>internal</code>: implementation which requires no libraries
112 * beyond JSAMP itself</li>
113 * <li>the classname of an implementation of this class which has a
114 * no-arg constructor</li>
115 * </ul>
116 *
117 * @return default instance of this class
118 */
119 public static XmlRpcKit getInstance() {
120 if ( defaultInstance_ == null ) {
121 defaultInstance_ = createDefaultInstance();
122 logger_.info( "Default XmlRpcInstance is " + defaultInstance_ );
123 }
124 return defaultInstance_;
125 }
126
127 /**
128 * Returns an XmlRpcKit instance given its name.
129 *
130 * @param name name of one of the known implementations, or classname
131 * of an XmlRpcKit implementatation with a no-arg
132 * constructor
133 * @return named implementation object
134 * @throws IllegalArgumentException if none by that name can be found
135 */
136 public static XmlRpcKit getInstanceByName( String name ) {
137
138 // Implementation specified by system property -
139 // try to find one with a matching name in the known list.
140 XmlRpcKit[] impls = KNOWN_IMPLS;
141 for ( int i = 0; i < impls.length; i++ ) {
142 if ( name.equalsIgnoreCase( impls[ i ].getName() ) ) {
143 return impls[ i ];
144 }
145 }
146
147 // Still not got one -
148 // try to interpret system property as class name.
149 Class clazz;
150 try {
151 clazz = Class.forName( name );
152 }
153 catch ( ClassNotFoundException e ) {
154 throw new IllegalArgumentException( "No such XML-RPC "
155 + "implementation \""
156 + name + "\"" );
157 }
158 try {
159 return (XmlRpcKit) clazz.newInstance();
160 }
161 catch ( Throwable e ) {
162 throw (RuntimeException)
163 new IllegalArgumentException( "Error instantiating custom "
164 + "XmlRpcKit "
165 + clazz.getName() )
166 .initCause( e );
167 }
168 }
169
170 /**
171 * Constructs the default instance of this class based on system property
172 * and class availability.
173 *
174 * @return XmlRpcKit object
175 * @see #getInstance
176 */
177 private static XmlRpcKit createDefaultInstance() {
178 XmlRpcKit[] impls = KNOWN_IMPLS;
179 String implName = System.getProperty( IMPL_PROP );
180 logger_.info( "Creating default XmlRpcInstance: " + IMPL_PROP + "=" +
181 implName );
182
183 // No implementation specified by system property -
184 // use the first one in the list that works.
185 if ( implName == null ) {
186 for ( int i = 0; i < impls.length; i++ ) {
187 if ( impls[ i ].isAvailable() ) {
188 return impls[ i ];
189 }
190 }
191 return impls[ 0 ];
192 }
193
194 // Implementation specified by system property -
195 // try to find one with a matching name in the known list.
196 else {
197 return getInstanceByName( implName );
198 }
199 }
200
201 /**
202 * Returns a new XmlRpcKit given classnames for the client and server
203 * factory classes. If the classes are not available, a kit which
204 * returns {@link #isAvailable}()=false will be returned.
205 *
206 * @param name kit name
207 * @param clientFactoryClassName name of class implementing
208 * SampXmlRpcClientFactory which has a no-arg constructor
209 * @param serverFactoryClassName name of class implementing
210 * SampXmlRpcServerFactory which has a no-arg constructor
211 * @return new XmlRpcKit constructed using reflection
212 */
213 public static XmlRpcKit createReflectionKit( String name,
214 String clientFactoryClassName,
215 String serverFactoryClassName
216 ) {
217 SampXmlRpcClientFactory clientFactory = null;
218 SampXmlRpcServerFactory serverFactory = null;
219 Throwable error = null;
220 try {
221 clientFactory = (SampXmlRpcClientFactory)
222 Class.forName( clientFactoryClassName )
223 .newInstance();
224 serverFactory = (SampXmlRpcServerFactory)
225 Class.forName( serverFactoryClassName )
226 .newInstance();
227 }
228 catch ( ClassNotFoundException e ) {
229 error = e;
230 }
231 catch ( LinkageError e ) {
232 error = e;
233 }
234 catch ( InstantiationException e ) {
235 error = e;
236 }
237 catch ( IllegalAccessException e ) {
238 error = e;
239 }
240 if ( clientFactory != null && serverFactory != null ) {
241 assert error == null;
242 return new AvailableKit( name, clientFactory, serverFactory );
243 }
244 else {
245 assert error != null;
246 return new UnavailableKit( name, error );
247 }
248 }
249
250 /**
251 * XmlRpcKit implementation which is available.
252 */
253 private static class AvailableKit extends XmlRpcKit {
254 private final String name_;
255 private final SampXmlRpcClientFactory clientFactory_;
256 private final SampXmlRpcServerFactory serverFactory_;
257
258 /**
259 * Constructor.
260 *
261 * @param name implementation name
262 * @param clientFactory SampXmlRpcClientFactory instance
263 * @param serverFactory SampXmlRpcServerFactory instance
264 */
265 AvailableKit( String name,
266 SampXmlRpcClientFactory clientFactory,
267 SampXmlRpcServerFactory serverFactory ) {
268 name_ = name;
269 clientFactory_ = clientFactory;
270 serverFactory_ = serverFactory;
271 }
272
273 public SampXmlRpcClientFactory getClientFactory() {
274 return clientFactory_;
275 }
276
277 public SampXmlRpcServerFactory getServerFactory() {
278 return serverFactory_;
279 }
280
281 public String getName() {
282 return name_;
283 }
284
285 public boolean isAvailable() {
286 return true;
287 }
288
289 public String toString() {
290 return name_;
291 }
292 }
293
294 /**
295 * XmlRpcKit implementation which always returns false from isAvailable
296 * and throws exceptions from getServer/Client factory methods.
297 */
298 private static class UnavailableKit extends XmlRpcKit {
299 private final String name_;
300 private final Throwable error_;
301
302 /**
303 * Constructor.
304 *
305 * @param kit name
306 * @param error the reason the kit is unavailable
307 */
308 UnavailableKit( String name, Throwable error ) {
309 name_ = name;
310 error_ = error;
311 }
312
313 public SampXmlRpcClientFactory getClientFactory() {
314 throw (RuntimeException)
315 new UnsupportedOperationException( name_
316 + " implementation not"
317 + " available" )
318 .initCause( error_ );
319 }
320
321 public SampXmlRpcServerFactory getServerFactory() {
322 throw (RuntimeException)
323 new UnsupportedOperationException( name_
324 + " implementation not"
325 + " available" )
326 .initCause( error_ );
327 }
328
329 public String getName() {
330 return name_;
331 }
332
333 public boolean isAvailable() {
334 return false;
335 }
336
337 public String toString() {
338 return name_;
339 }
340 }
341
342 /**
343 * Returns an available or unavailable XmlRpcKit based on Apache XML-RPC
344 * version 1.2.
345 *
346 * @param name kit name
347 * @return new kit
348 */
349 private static XmlRpcKit createApacheKit( String name ) {
350 XmlRpcKit kit = createReflectionKit(
351 name,
352 "org.astrogrid.samp.xmlrpc.apache.ApacheClientFactory",
353 "org.astrogrid.samp.xmlrpc.apache.ApacheServerFactory" );
354 if ( kit.isAvailable() ) {
355 try {
356 Class xClazz = Class.forName( "org.apache.xmlrpc.XmlRpc" );
357 Field vField = xClazz.getField( "version" );
358 Object version = Modifier.isStatic( vField.getModifiers() )
359 ? vField.get( null )
360 : null;
361 if ( version instanceof String
362 && ((String) version)
363 .startsWith( "Apache XML-RPC 1.2" ) ) {
364 return kit;
365 }
366 else {
367 String msg = "Wrong Apache XML-RPC version: " + version
368 + " not 1.2";
369 return
370 new UnavailableKit( name,
371 new ClassNotFoundException( msg ) );
372 }
373 }
374 catch ( Throwable e ) {
375 return new UnavailableKit( name, e );
376 }
377 }
378 else {
379 return kit;
380 }
381 }
382 }