View Javadoc

1   /*
2    * Copyright 2006-2008 the original author or authors.
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.springframework.osgi.extender;
18  
19  import org.osgi.framework.BundleContext;
20  import org.springframework.osgi.context.DelegatedExecutionOsgiBundleApplicationContext;
21  
22  /**
23   * Extender hook for customizing the OSGi application context creation. Each
24   * bundle started by the OSGi platform can create (or customize) an application
25   * context that becomes managed by the Spring-DM extender.
26   * 
27   * For example, to create an application context based on the presence of a
28   * manifest header, one could use the following code:
29   * 
30   * <pre class="code">
31   * class HeaderBasedAppCtxCreator implements OsgiApplicationContextCreator {
32   * 
33   * 	/** location header &#42;/
34   * 	private static final String HEADER = &quot;Context-Locations&quot;;
35   * 
36   * 
37   * 	public DelegatedExecutionOsgiBundleApplicationContext createApplicationContext(BundleContext bundleContext) {
38   * 		Bundle owningBundle = bundleContext.getBundle();
39   * 
40   * 		Object value = owningBundle.getHeaders().get(HEADER);
41   * 		String[] locations = null;
42   * 		if (value != null &amp;&amp; value instanceof String) {
43   * 			locations = StringUtils.commaDelimitedListToStringArray((String) value);
44   * 		}
45   * 		else {
46   * 			locations = &lt;default values&gt;
47   * 		}
48   * 
49   * 		// create application context from 'locations'  
50   * 		
51   * 		return applicationContext;	
52   * 	}
53   * }
54   * </pre>
55   * 
56   * <p/><b>Note:</b> The application contexts should be only created and
57   * initialized but not started (i.e. <code>refresh()</code> method should not
58   * be called).
59   * 
60   * <p/>The recommended way of configuring the extender is to attach any relevant
61   * <code>OsgiApplicationContextCreator</code> implementation as fragments to
62   * extender bundle. Please see the OSGi specification and Spring-DM reference
63   * documentation for more information on how to do that.
64   * 
65   * <p/>Note the extender also supports <code>OsgiBeanFactoryPostProcessor</code>
66   * for application context customization.
67   * 
68   * <p/>The creation of an application context doesn't guarantee that a bundle
69   * becomes Spring-DM managed. The Spring-DM extender can do additional post
70   * filtering that can discard the bundle (and associated context).
71   * 
72   * @author Costin Leau
73   * 
74   */
75  public interface OsgiApplicationContextCreator {
76  
77  	/**
78  	 * Creates an application context for the given bundle context. If no
79  	 * application context needs to be created, then <code>null</code> should
80  	 * be returned. Exceptions will be caught and logged but will not prevent the
81  	 * creation of other application contexts.
82  	 * 
83  	 * @param bundleContext OSGi bundle context determining the context creation
84  	 * @return <code>null</code> if no context should be created, non-<code>null</code>
85  	 * otherwise
86  	 * @throws Exception if something goes wrong
87  	 */
88  	DelegatedExecutionOsgiBundleApplicationContext createApplicationContext(BundleContext bundleContext)
89  			throws Exception;
90  }