1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>ECF Shared Object Factory</title>
<style type="text/css">@import url("../../book.css");</style>
<style type="text/css">@import url("../../schema.css");</style>
</HEAD>
<BODY>
<H1 style="text-align:center">ECF Shared Object Factory</H1>
<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Identifier: </h6>org.eclipse.ecf.sharedObjectFactory<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Since: </h6>0.6.0
<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Description: </h6>ECF Shared Object Factory extension point (<b>org.eclipse.ecf.sharedObjectFactory</b>. This extension point allows implmenters to define an <b>org.eclipse.ecf.core.sharedobject.provider.ISharedObjectInstantiator</b> that will be responsible for creating
<b>org.eclipse.ecf.core.sharedobject.ISharedObject</b> instances when requested by clients. Here is the <b>ISharedObjectInstantiator</b> that
extensions must implement:
<pre class="Example"><span class="code SchemaTag">
public interface ISharedObjectInstantiator {
/**
* Create instance of ISharedObject. This is the interface that plugin
* implementations must implement for the sharedObjectFactory extension
* point. The caller may optionally specify both argument types and
* arguments that will be passed into this method (and therefore to the
* provider implementation implementing this method). For example:
* <p>
* </p>
* <p>
* <b>
* SharedObjectFactory.getDefault().createSharedObject("foosharedobject",new
* String [] { java.lang.String }, new Object { "hello" });</b>
* </p>
* <p>
* </p>
*
* @param typeDescription
* the SharedObjectTypeDescription associated with the registered
* shared object provider implementation plugin
* @param args
* arguments specified by the caller. May be null if no arguments
* are passed in by caller to
* SharedObjectFactory.getDefault().createSharedObject(...)
* @return ISharedObject instance. The provider implementation must return a
* valid object implementing ISharedObject OR throw a
* SharedObjectCreateException
* @throws SharedObjectCreateException
* if shared object instance cannot be created
*/
public ISharedObject createInstance(
SharedObjectTypeDescription typeDescription, Object[] args)
throws SharedObjectCreateException;
}
</span></pre><p></p>
<h6 class="CaptionFigColumn SchemaHeader">Configuration Markup:</h6>
<p></p>
<p class="code SchemaDtd"><!ELEMENT <a name="e.extension">extension</a> (<a href="#e.sharedObjectFactory">sharedObjectFactory</a>+)></p>
<p class="code SchemaDtd"><!ATTLIST extension</p>
<p class="code SchemaDtdAttlist">point CDATA #REQUIRED<p class="code SchemaDtdAttlist">id CDATA #IMPLIED<p class="code SchemaDtdAttlist">name CDATA #IMPLIED></p>
<p></p>
<ul class="ConfigMarkupAttlistDesc">
</ul>
<br><p class="code SchemaDtd"><!ELEMENT <a name="e.sharedObjectFactory">sharedObjectFactory</a> (<a href="#e.property">property</a>*)></p>
<p class="code SchemaDtd"><!ATTLIST sharedObjectFactory</p>
<p class="code SchemaDtdAttlist">class CDATA #REQUIRED<p class="code SchemaDtdAttlist">name CDATA #IMPLIED<p class="code SchemaDtdAttlist">description CDATA #IMPLIED></p>
<p></p>
<ul class="ConfigMarkupAttlistDesc">
<li><b>class</b> - The fully qualified name of the class that implements the <b>org.eclipse.ecf.core.provider.ISharedObjectInstantiator</b> interface.</li>
<li><b>name</b> - An optional name for the extension. If no name is explicitly provided by the extension, the sharedObjectFactory class name is used as the name. Note that this name must <b>not</b> conflict with any other name in the ECF SharedObjectFactory in order to be successfully registered. Care should therefore be taken in selection of a name such that it does not conflict with other pre-existing names for this factory implementations</li>
<li><b>description</b> - </li>
</ul>
<br><p class="code SchemaDtd"><!ELEMENT <a name="e.property">property</a> EMPTY></p>
<p class="code SchemaDtd"><!ATTLIST property</p>
<p class="code SchemaDtdAttlist">name CDATA #REQUIRED<p class="code SchemaDtdAttlist">value CDATA #REQUIRED></p>
<p></p>
<p class="ConfigMarkupElementDesc">
Property (name,value) associated with SharedObjectTypeDescription</p>
<br>
<ul class="ConfigMarkupAttlistDesc">
<li><b>name</b> - The name of the property</li>
<li><b>value</b> - The value of the property</li>
</ul>
<br><h6 class="CaptionFigColumn SchemaHeader">Examples: </h6>Here's an example of an extension point declaration:
<pre class="Example"><span class="code SchemaTag">
<extension
point=</span><span class="code SchemaCstring">"org.eclipse.ecf.sharedobject.sharedObjectFactory"</span><span class="code SchemaTag">>
<sharedObjectFactory
class=</span><span class="code SchemaCstring">"org.eclipse.ecf.tests.provider.TestSharedObjectInstantiator"</span><span class="code SchemaTag">
name=</span><span class="code SchemaCstring">"ecf.test.sharedobjectfactory"</span><span class="code SchemaTag">/>
</extension>
</span></pre>
and the TestSharedObjectInstantiator is defined:
<pre class="Example"><span class="code SchemaTag">
public class TestSharedObjectInstantiator implements ISharedObjectInstantiator {
public ISharedObject createInstance(SharedObjectTypeDescription description, Object[] args) throws SharedObjectCreateException {
System.out.println("createInstance("+description+","+((args==null)?"null":Arrays.asList(args).toString()));
return new TestSharedObject();
}
}
</span></pre>
<h3>Example Usage of Container by Clients</h3>
Clients may use the extension via calls such as:
<pre class="Example"><span class="code SchemaTag">
ISharedObject obj = SharedObjectFactory.getDefault().createSharedObject("ecf.test.sharedobjectfactory");
</span></pre>
<p></p>
<h6 class="CaptionFigColumn SchemaHeader">API Information: </h6>The API for accessing the functionality provided via extensions is via <b>org.eclipse.ecf.core.sharedobject.SharedObjectFactory.getDefault()</b> methods. Specifically, the <b>org.eclipse.ecf.core.sharedobject.ISharedObjectFactory.createSharedObject()</b> methods are to be used to create shared
object instances, where extensions implement the actual shared object creation
Here is the <b>org.eclipse.ecf.core.sharedobject.ISharedObjectFactory</b> contract implemented by the <b>org.eclipse.ecf.core.sharedobject.SharedObjectFactory</b>:
<pre class="Example"><span class="code SchemaTag">
public interface ISharedObjectFactory {
/*
* Add a SharedObjectTypeDescription to the set of known
* SharedObjectTypeDescriptions.
*
* @param scd the SharedObjectTypeDescription to add to this factory @return
* SharedObjectTypeDescription the old description of the same name, null if
* none found
*/
public SharedObjectTypeDescription addDescription(
SharedObjectTypeDescription description);
/**
* Get a collection of the SharedObjectTypeDescriptions currently known to
* this factory. This allows clients to query the factory to determine what
* if any other SharedObjectTypeDescriptions are currently registered with
* the factory, and if so, what they are.
*
* @return List of SharedObjectTypeDescription instances. Will not be null.
*/
public List getDescriptions();
/**
* Check to see if a given named description is already contained by this
* factory
*
* @param description
* the SharedObjectTypeDescription to look for
* @return true if description is already known to factory, false otherwise
*/
public boolean containsDescription(SharedObjectTypeDescription description);
/**
* Get the known SharedObjectTypeDescription given it's name.
*
* @param name
* @return SharedObjectTypeDescription found. Null if description not found.
* @throws SharedObjectCreateException
*/
public SharedObjectTypeDescription getDescriptionByName(String name)
throws SharedObjectCreateException;
/**
* Create ISharedObject instance. Given a SharedObjectTypeDescription
* object, a String [] of argument types, and an Object [] of parameters,
* this method will
* <p>
* <ul>
* <li>lookup the known SharedObjectTypeDescriptions to find one of
* matching name</li>
* <li>if found, will retrieve or create an ISharedObjectInstantiator for
* that description</li>
* <li>Call the ISharedObjectInstantiator.createInstance method to return
* an instance of ISharedObject</li>
* </ul>
*
* @param typeDescription
* the SharedObjectTypeDescription to use to create the instance
* @param args
* an Object [] of arguments passed to the createInstance method
* of the ISharedObjectInstantiator
* @return a valid instance of ISharedObject. Will not be null.
* @throws SharedObjectCreateException
* if shared object cannot be created
*/
public ISharedObject createSharedObject(
SharedObjectTypeDescription typeDescription, Object[] args)
throws SharedObjectCreateException;
/**
* Create ISharedObject instance. Given a SharedObjectTypeDescription name,
* this method will
* <p>
* <ul>
* <li>lookup the known SharedObjectTypeDescriptions to find one of
* matching name</li>
* <li>if found, will retrieve or create an ISharedObjectInstantiator for
* that description</li>
* <li>Call the ISharedObjectInstantiator.createInstance method to return
* an instance of ISharedObject</li>
* </ul>
*
* @param descriptionName
* the SharedObjectTypeDescription name to lookup
* @return a valid instance of ISharedObject. Will not be null.
* @throws SharedObjectCreateException
*/
public ISharedObject createSharedObject(String descriptionName)
throws SharedObjectCreateException;
/**
* Create ISharedObject instance. Given a SharedObjectTypeDescription name,
* this method will
* <p>
* <ul>
* <li>lookup the known SharedObjectTypeDescriptions to find one of
* matching name</li>
* <li>if found, will retrieve or create an ISharedObjectInstantiator for
* that description</li>
* <li>Call the ISharedObjectInstantiator.createInstance method to return
* an instance of ISharedObject</li>
* </ul>
*
* @param descriptionName
* the SharedObjectTypeDescription name to lookup
* @param args
* the Object [] of arguments passed to the
* ISharedObjectInstantiator.createInstance method
* @return a valid instance of IContainer. Will not be null.
* @throws SharedObjectCreateException
*/
public ISharedObject createSharedObject(String descriptionName,
Object[] args) throws SharedObjectCreateException;
/**
* Remove given description from set known to this factory.
*
* @param scd
* the SharedObjectTypeDescription to remove
* @return the removed SharedObjectTypeDescription, null if nothing removed
*/
public SharedObjectTypeDescription removeDescription(
SharedObjectTypeDescription scd);
}
</span></pre>
See the "Examples" page for an example usage of the extension point.
<p></p>
<br>
<p class="note SchemaCopyright">
Copyright (c) 2004 Composent, Inc. and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html. Contributors: Composent, Inc. - initial API and implementation
</p>
</BODY>
</HTML>
|
