Attachment #32331 for bug #113863

Lines 55-61 Link Here

(-)buildDoc.xml (-1 lines)
55		55
56	<include name="org.eclipse.gmf.runtime.emf.core/doc/org_eclipse_gmf_runtime_emf_core_MetaModelProviders.html"/>	56	<include name="org.eclipse.gmf.runtime.emf.core/doc/org_eclipse_gmf_runtime_emf_core_MetaModelProviders.html"/>
57	<include name="org.eclipse.gmf.runtime.emf.core/doc/org_eclipse_gmf_runtime_emf_core_Pathmaps.html"/>	57	<include name="org.eclipse.gmf.runtime.emf.core/doc/org_eclipse_gmf_runtime_emf_core_Pathmaps.html"/>
58	<include name="org.eclipse.gmf.runtime.emf.core/doc/org_eclipse_gmf_runtime_emf_core_resourcePolicies.html"/>
59		58
60	<include name="org.eclipse.gmf.runtime.emf.ui/doc/org_eclipse_gmf_runtime_emf_ui_modelingAssistantProviders.html"/>	59	<include name="org.eclipse.gmf.runtime.emf.ui/doc/org_eclipse_gmf_runtime_emf_ui_modelingAssistantProviders.html"/>
61		60

Lines 26-32 Link Here

(-)toc-common-ext-pt.xml (-1 lines)
26	<topic label="org.eclipse.gmf.runtime.common.ui.services.properties.propertyModifiers" href="reference/extension-points/org_eclipse_gmf_runtime_common_ui_services_properties_propertyModifiers.html" />	26	<topic label="org.eclipse.gmf.runtime.common.ui.services.properties.propertyModifiers" href="reference/extension-points/org_eclipse_gmf_runtime_common_ui_services_properties_propertyModifiers.html" />
27	<topic label="org.eclipse.gmf.runtime.emf.core.MetaModelProviders" href="reference/extension-points/org_eclipse_gmf_runtime_emf_core_MetaModelProviders.html" />	27	<topic label="org.eclipse.gmf.runtime.emf.core.MetaModelProviders" href="reference/extension-points/org_eclipse_gmf_runtime_emf_core_MetaModelProviders.html" />
28	<topic label="org.eclipse.gmf.runtime.emf.core.Pathmaps" href="reference/extension-points/org_eclipse_gmf_runtime_emf_core_Pathmaps.html" />	28	<topic label="org.eclipse.gmf.runtime.emf.core.Pathmaps" href="reference/extension-points/org_eclipse_gmf_runtime_emf_core_Pathmaps.html" />
29	<topic label="org.eclipse.gmf.runtime.emf.core.resourcePolicies" href="reference/extension-points/org_eclipse_gmf_runtime_emf_core_resourcePolicies.html" />
30	<topic label="org.eclipse.gmf.runtime.emf.ui.modelingAssistantProviders" href="reference/extension-points/org_eclipse_gmf_runtime_emf_ui_modelingAssistantProviders.html" />	29	<topic label="org.eclipse.gmf.runtime.emf.ui.modelingAssistantProviders" href="reference/extension-points/org_eclipse_gmf_runtime_emf_ui_modelingAssistantProviders.html" />
31	<topic label="org.eclipse.gmf.runtime.emf.clipboard.core.clipboardSupport" href="reference/extension-points/org_eclipse_gmf_runtime_emf_clipboard_core_clipboardSupport.html" />	30	<topic label="org.eclipse.gmf.runtime.emf.clipboard.core.clipboardSupport" href="reference/extension-points/org_eclipse_gmf_runtime_emf_clipboard_core_clipboardSupport.html" />
32	<topic label="org.eclipse.gmf.runtime.emf.type.core.elementTypes" href="reference/extension-points/org_eclipse_gmf_runtime_emf_type_elementTypes.html" />	31	<topic label="org.eclipse.gmf.runtime.emf.type.core.elementTypes" href="reference/extension-points/org_eclipse_gmf_runtime_emf_type_elementTypes.html" />

Lines 38-44 Link Here

(-)html/reference/extension-points/index.html (-1 lines)
38		38
39	<li><a href="org_eclipse_gmf_runtime_emf_core_MetaModelProviders.html">org.eclipse.gmf.runtime.emf.core.MetaModelProviders</a></li>	39	<li><a href="org_eclipse_gmf_runtime_emf_core_MetaModelProviders.html">org.eclipse.gmf.runtime.emf.core.MetaModelProviders</a></li>
40	<li><a href="org_eclipse_gmf_runtime_emf_core_Pathmaps.html">org.eclipse.gmf.runtime.emf.core.Pathmaps</a></li>	40	<li><a href="org_eclipse_gmf_runtime_emf_core_Pathmaps.html">org.eclipse.gmf.runtime.emf.core.Pathmaps</a></li>
41	<li><a href="org_eclipse_gmf_runtime_emf_core_resourcePolicies.html">org.eclipse.gmf.runtime.emf.core.resourcePolicies</a></li>
42		41
43	<li><a href="org_eclipse_gmf_runtime_emf_ui_modelingAssistantProviders.html">org.eclipse.gmf.runtime.emf.ui.modelingAssistantProviders</a></li>	42	<li><a href="org_eclipse_gmf_runtime_emf_ui_modelingAssistantProviders.html">org.eclipse.gmf.runtime.emf.ui.modelingAssistantProviders</a></li>
44		43




<h3>Introduction</h3>
<p>
This example describes the usage of model management framework within the SDK.
It demonstrates some of the model management capabilities (editing domain, validation,
batched notification, semantic procedures etc.) applied to library models.
</p>

<h3>References</h3>

This plug-in contributes the <b>MSL</b> menu to the MSL library editor's main menu and context menu.
The menu has the following actions:
<ol>
<li><b>Control Unit:</b> Creates a new separate resource (controlled unit) in a
    logical resource.  The new resource's URI is determined automatically
    by an extension point</li>
<li><b>Uncontrol Unit:</b> Absorbs a separate resource in a logical resource
    into its container</li>
<li><b>Edit:</b> Allows to edit the properties of a library model element. The changes made will be
committed as a whole or can be undone as a whole (demonstrates the concept of an <code>MUndoInterval</code>)</li>
<li><b>Create Resource:</b> Creates a library resource</li>

<li>Unified Transaction Semantics</li>
<li>Undo/Redo management</li>
<li>Multi-threaded access control</li>
<li>Management of logical resources persisted in multiple physical resources</li>
<li>Batch notification of events</li>
<li>Evaluation of live constraints</li>
<li>Common read and write operations</li>





<table border="0" cellspacing="8" cellpadding="0">
 <tr>
  <td>Version: 0.2</td>
  <td>Date: Dec. 28, 2005</td>
  <!-- Removed references to the Logical Resource API -->
 </tr>
</table>


  <li><a href="#intro">Introduction</a></li>
  <li><a href="#editing_domain">Creating and Using an MSL Editing Domain</a></li>
  <li><a href="#making_changes">Making Changes to Resources</a></li>
  <li><a href="#logical">Working with Logical Resources</a></li>
  <li><a href="#listeners">MSL Listeners</a></li>
  <li><a href="#validation">Model Validation</a></li>
  <li><a href="#copy_paste">MSL Copy and Paste Support</a></li>

<p class="backto"><font size="-1">[<a href="#top">back to top</a>]</font></p>

<p>
The Model Service Layer (MSL) provides a number of facilities to ease model management:
model modification semantics, uniform resource creation and loading, uniform listener
registration, batching of notifications, live validation with automatic modification
abandonment, copy/paste support, automated pathmap support and additional metamodel support.

editingDomain.saveResource(r1);
</pre>

<h2><a name="logical"></a>Working with Logical Resources</h2>

<p class="backto"><font size="-1">[<a href="#top">back to top</a>]</font></p>

<p>
The MSL's default resource implementation conforms to the
<a href="../../reference/api/common/org/eclipse/gmf/runtime/emf/core/resources/ILogicalResource.html"><code>ILogicalResource</code></a>
interface.  This resource creates an in-memory logical view of an EMF tree
(or forest) structure that is persisted in multiple physical resources, all of
which are XMI-compliant.  The central concept in the logical-to-physical mapping
of an MSL resource is the "separate" element.  A separate elements is persisted
in a different, or separate, physical resource than its container.
</p><p>
To obtain a logical resource, use the editing domain to create a resource as
described <a href="#create_resource">above</a> and then get a view of it as
an <code>ILogicalResource</code>.
To store a model element in its own physical resource, just ask the logical
resource to separate it into a new resource on a URI of your choosing.  Don't
forget to ask first whether it <i>can</i> be separated (the metamodel may
implement rules restricting what can be separated; see below):
</p>
<pre class="snippet">
Resource r1 = 
	editingDomain.createResource("file://c:/eclipse/workspace/aProject/test.rmplibrary", 
					RMPLibraryPackage.eINSTANCE.getLibrary());
ILogicalResource logical = editingDomain.asLogicalResource(r1);

// ... fill the resource with contents

EObject element = // ... find an element to be separated

if (logical.canSeparate(element)) {
    try {
        logical.separate(
            element,
            URI.createURI("file://c:/eclipse/workspace/aProject/test.sub1.rmplibrary"));
    } catch (CannotSeparateException e) {
        System.out.println("Could not separate the element: " + element);
        e.printStackTrace();
    }
}

editingDomain.saveResource(logical);  // or logical.save(Collections.EMPTY_MAP);
</pre>
<p>
We now have one logical resource stored in two files.
</p><p>
Note the use of the <code>ILogicalResource MEditingDomain.asLogicalResource(Resource)</code>
method to obtain a view of an arbitrary resource as a logical resource.  This is
necessary because the editing domain might actually instantiate any resource
implementation, not necessarily a logical resource, depending on the registered
resource factories.  If the resource is not actually a logical resource, then
this method creates a wrapper that provides compatibility with the logical
resource API.
</p><p>
In the snippet above, we catch <code>CannotSeparateException</code> despite
being informed that the separation would be permitted because there may be
unexpected conditions that prevent the separation from succeeding (such as
incorrect file permissions).  No attempt is made to actually persist the new
physical resource until the logical resource is saved, but a metamodel extension
might be proactive in checking even at this point whether certain I/O limitations
would be exceeded.
</p><p>
To do the inverse of a separation operation, we can <i>absorb</i> an element
from a separate resource into the same resource as its container:
</p>

<pre class="snippet">
if (logical.isSeparate(element)) {
    try {
        logical.absorb(element);
    } catch (CannotAbsorbException e) {
        System.out.println("Could not absorb the element: " + element);
        e.printStackTrace();
    }
}

editingDomain.saveResource(logical);
</pre>
<p>
Now, our logical resource is again stored in a single file.  Note that the
<tt>test.sub1.rmplibrary</tt> file is not deleted, though it will be empty.
This simplifies comparing and merging changes with a source control repository.
Note also that, like separation, absorption can fail unexpectedly.
</p><p>
How does the MSL framework determine whether an element can be separated?  By
default, any element of any EMF metamodel can be separated, unless it is a
root of the logical resource or has already been separated.  However, a metamodel
provider or an application may for some reason want to restrict the elements
that may be separated.  This is accomplished by registering a policy on the
<a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_resourcePolicies.html"><code>org.eclipse.gmf.runtime.emf.core.resourcePolicies</code></a>
extension point:
</p>
<pre class="snippet">
&lt;extension
      point="org.eclipse.gmf.runtime.emf.core.resourcePolicies"&gt;
   &lt;policy
         class="org.eclipse.gmf.examples.runtime.emf.resources.LibraryResourcePolicy"
         nsURI="http:///com/ibm/xtools/emf/metamodel/example/pde/rmplibrary.ecore/1.0.0"/&gt;
&lt;/extension&gt;
</pre>
<p>
The policy implements the
<a href="../../reference/api/common/org/eclipse/gmf/runtime/emf/core/resources/ILogicalResourcePolicy.html"><code>ILogicalResourcePolicy</code></a>
interface, usually by extending the <code>AbstractLogicalResourcePolicy</code>
class.  Our example allows only libraries to be separated:
</p>
<pre class="snippet">
public class LibraryResourcePolicy
    extends AbstractLogicalResourcePolicy {

    public boolean canSeparate(ILogicalResource resource, EObject eObject) {
        return eObject instanceof Library;
    }
}
</pre>
<p>
Policies can also suggest default URIs for new physical resources according to
some application-specific naming system, implement extra checks when clients
perform separations or absorptions, etc.
</p><p>
By default, logical resources initially load only the root resource (corresponding
to the logical URI) and automatically load other resources as they are needed
by access of containment references or proxy resolution.  The <code>ILogicalResource</code>
interface defines load options to disable incremental loading or to initially
load the entire logical resource contents.  Automatic incremental loading of
separate objects from containment references requires a custom <code>EList</code>
that loads the necessary resources on demand.  Two convenient implementations
are provided by the MSL for metamodels to use in place of the
<code>EObjectContainmentEList</code> and <code>EObjectContainmentWithInverseEList</code>
classes.  However, it may be necessary for a metamodel to be deployable without
the MSL, in a "pure EMF" configuration.  To address this need, the
<code>resourcePolicies</code> extension point allows the registration of
an <code>EFactory</code> that creates alternative <code>*Impl</code> classes
that use these special lists, to be deployed only in MSL configurations:
</p>
<pre class="snippet">
&lt;extension
      point="org.eclipse.gmf.runtime.emf.core.resourcePolicies"&gt;
   &lt;efactory
          class="org.eclipse.gmf.examples.runtime.emf.resources.LoadingRMPLibraryFactoryImpl"
          nsURI="http:///com/ibm/xtools/emf/metamodel/example/pde/rmplibrary.ecore/1.0.0"/&gt;
&lt;/extension&gt;
</pre>
<p>
The MSL framework will use this factory instead of the default when loading
a logical resource; it does not need to be used by clients to create new objects.
In our example, only libraries can be separated and only libraries can contain
other libraries, so our factory simply creates a specialization of the default
<code>LibraryImpl</code> class:
</p>
<pre class="snippet">
public class LoadingRMPLibraryFactoryImpl
    extends RMPLibraryFactoryImpl {

    public Library createLibrary() {
        return new LoadingLibraryImpl();
    }
	
    public EPackage getEPackage() {
        return RMPLibraryPackage.eINSTANCE;
    }
}

class LoadingLibraryImpl
    extends LibraryImpl {

    public LoadingLibraryImpl() {
        super();

        // use the custom containment-with-inverse list to perform automatic
        //   loading of contained elements in this feature.  This pre-empts
        //   the superclass's lazy initialization of this list
        branches = new EObjectContainmentWithInverseLoadingEList(
            Library.class, this, RMPLibraryPackage.LIBRARY__BRANCHES,
            RMPLibraryPackage.LIBRARY__PARENT_BRANCH);
    }
}
</pre>
<p>
Note how we only concern ourselves here with overriding the implementation of
those features that will be able to contain separate elements.
</p>

<h2><a name="listeners"></a>MSL Listeners</h2>

<p class="backto"><font size="-1">[<a href="#top">back to top</a>]</font></p>

<li>Registered the MSL resource factory for the .rmplibrary file extension</li>
<li>Made changes to MSL resources using an undo interval and a write action</li>
<li>Undid and redid the changes made during an undo interval</li>
<li>Created logical resources consisting of multiple files</li>
<li>Customized the management of logical resources for library models</li>
<li>Registerd an MSL listener that informed us whenever a resource was dirtied</li>
<li>Learned how live validation can be used to enforce resource integrity during write actions</li>
<li>Learned how to perform batch validation when using MSL</li>




<li>Unified Transaction Semantics</li>
<li>Undo/Redo management</li>
<li>Multi-threaded access control</li>
<li>Logical or composite resources</li>
<li>Batch notification of events</li>
<li>Evaluation of live constraints</li>
<li>Common read and write operations</li>

of all concrete commands that perform model operations. Clients must provide a definition of the <code>doExecute()</code>
method to perform some operation. All model commands have an associated undo interval, through which they can be undone
or redone.</li>
<li><b>Logical resource support</b>: The extension point <a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_resourcePolicies.html">org.eclipse.gmf.runtime.emf.core.resourcePolicies</a> is defined for
EMF meta-model providers to provide policies that customize the resource structure for their models.  The <code>ILogicalResource</code>
interface provides a logical view in memory of a tree structure that is persisted in multiple physical resources.
Metamodel-specific customizations are provided as <code>ILogicalResourcePolicy</code> implementations that define
the locations in a logical structure where boundaries in the physical structure are permitted and provide automatic
naming of physical resources.  <code>EFactory</code> implementations registered on this extension point provide support
for incremental loading of logical resources.</li>
<li><b>Path map support</b>: The extension point <a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_Pathmaps.html">org.eclipse.gmf.runtime.emf.core.Pathmaps</a> is defined for path map
variables. Path map variables allow for portability of URIs, similar to Eclipse's core path variables. The actual location
indicated by a URI depends on the run-time binding of the path variable. Thus, different environments can work with the

<ul>
  <li><code>EventTypes.CREATE</code>, <code>EventTypes.DESTROY</code></li>
  <li><code>EventTypes.IMPORT</code>, <code>EventTypes.EXPORT</code></li>
  <li><code>EventTypes.UNRESOLVE</code></li></ul></li>
  <li><code>EventTypes.SEPARATE</code>, <code>EventTypes.ABSORB</code>, <code>EventTypes.LOAD</code></li></ul></li>
<li><b>Meta-model Support</b>: The extension point <a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_MetaModelProviders.html">org.eclipse.gmf.runtime.emf.core. MetaModelProviders</a> allows 
clients to provide meta-model support services. Providers implement the interface <code>IMetamodelSupportProvider</code>.
The implementation of the interface method <code>getMetamodelSupport</code> returns the <code>IMetamodelSupport</code> object.

Return to bug 113863

Lines 276-282 Link Here

(-)html/howto/RMP_MSL_HowToDoc.html (-10 / +1 lines)
276	<li>Unified Transaction Semantics</li>	276	<li>Unified Transaction Semantics</li>
277	<li>Undo/Redo management</li>	277	<li>Undo/Redo management</li>
278	<li>Multi-threaded access control</li>	278	<li>Multi-threaded access control</li>
279	<li>Logical or composite resources</li>
280	<li>Batch notification of events</li>	279	<li>Batch notification of events</li>
281	<li>Evaluation of live constraints</li>	280	<li>Evaluation of live constraints</li>
282	<li>Common read and write operations</li>	281	<li>Common read and write operations</li>
Lines 305-317 Link Here
305	of all concrete commands that perform model operations. Clients must provide a definition of the <code>doExecute()</code>	304	of all concrete commands that perform model operations. Clients must provide a definition of the <code>doExecute()</code>
306	method to perform some operation. All model commands have an associated undo interval, through which they can be undone	305	method to perform some operation. All model commands have an associated undo interval, through which they can be undone
307	or redone.</li>	306	or redone.</li>
308	<li><b>Logical resource support</b>: The extension point <a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_resourcePolicies.html">org.eclipse.gmf.runtime.emf.core.resourcePolicies</a> is defined for
309	EMF meta-model providers to provide policies that customize the resource structure for their models. The <code>ILogicalResource</code>
310	interface provides a logical view in memory of a tree structure that is persisted in multiple physical resources.
311	Metamodel-specific customizations are provided as <code>ILogicalResourcePolicy</code> implementations that define
312	the locations in a logical structure where boundaries in the physical structure are permitted and provide automatic
313	naming of physical resources. <code>EFactory</code> implementations registered on this extension point provide support
314	for incremental loading of logical resources.</li>
315	<li><b>Path map support</b>: The extension point <a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_Pathmaps.html">org.eclipse.gmf.runtime.emf.core.Pathmaps</a> is defined for path map	307	<li><b>Path map support</b>: The extension point <a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_Pathmaps.html">org.eclipse.gmf.runtime.emf.core.Pathmaps</a> is defined for path map
316	variables. Path map variables allow for portability of URIs, similar to Eclipse's core path variables. The actual location	308	variables. Path map variables allow for portability of URIs, similar to Eclipse's core path variables. The actual location
317	indicated by a URI depends on the run-time binding of the path variable. Thus, different environments can work with the	309	indicated by a URI depends on the run-time binding of the path variable. Thus, different environments can work with the
Lines 338-345 Link Here
338	<ul>	330	<ul>
339	<li><code>EventTypes.CREATE</code>, <code>EventTypes.DESTROY</code></li>	331	<li><code>EventTypes.CREATE</code>, <code>EventTypes.DESTROY</code></li>
340	<li><code>EventTypes.IMPORT</code>, <code>EventTypes.EXPORT</code></li>	332	<li><code>EventTypes.IMPORT</code>, <code>EventTypes.EXPORT</code></li>
341	<li><code>EventTypes.UNRESOLVE</code></li>	333	<li><code>EventTypes.UNRESOLVE</code></li></ul></li>
342	<li><code>EventTypes.SEPARATE</code>, <code>EventTypes.ABSORB</code>, <code>EventTypes.LOAD</code></li></ul></li>
343	<li><b>Meta-model Support</b>: The extension point <a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_MetaModelProviders.html">org.eclipse.gmf.runtime.emf.core. MetaModelProviders</a> allows	334	<li><b>Meta-model Support</b>: The extension point <a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_MetaModelProviders.html">org.eclipse.gmf.runtime.emf.core. MetaModelProviders</a> allows
344	clients to provide meta-model support services. Providers implement the interface <code>IMetamodelSupportProvider</code>.	335	clients to provide meta-model support services. Providers implement the interface <code>IMetamodelSupportProvider</code>.
345	The implementation of the interface method <code>getMetamodelSupport</code> returns the <code>IMetamodelSupport</code> object.	336	The implementation of the interface method <code>getMetamodelSupport</code> returns the <code>IMetamodelSupport</code> object.

Lines 11-18 Link Here

(-)html/examples-guide/msl/modelManagementExample.html (-8 / +2 lines)
11	<h3>Introduction</h3>	11	<h3>Introduction</h3>
12	<p>	12	<p>
13	This example describes the usage of model management framework within the SDK.	13	This example describes the usage of model management framework within the SDK.
14	It demonstrates some of the model management capabilities (editing domain, validation	14	It demonstrates some of the model management capabilities (editing domain, validation,
15	batch notification, semantic procedures etc.) applied to library models.	15	batched notification, semantic procedures etc.) applied to library models.
16	</p>	16	</p>
17		17
18	<h3>References</h3>	18	<h3>References</h3>
Lines 35-45 Link Here
35	This plug-in contributes the <b>MSL</b> menu to the MSL library editor's main menu and context menu.	35	This plug-in contributes the <b>MSL</b> menu to the MSL library editor's main menu and context menu.
36	The menu has the following actions:	36	The menu has the following actions:
37	<ol>	37	<ol>
38	<li><b>Control Unit:</b> Creates a new separate resource (controlled unit) in a
39	logical resource. The new resource's URI is determined automatically
40	by an extension point</li>
41	<li><b>Uncontrol Unit:</b> Absorbs a separate resource in a logical resource
42	into its container</li>
43	<li><b>Edit:</b> Allows to edit the properties of a library model element. The changes made will be	38	<li><b>Edit:</b> Allows to edit the properties of a library model element. The changes made will be
44	committed as a whole or can be undone as a whole (demonstrates the concept of an <code>MUndoInterval</code>)</li>	39	committed as a whole or can be undone as a whole (demonstrates the concept of an <code>MUndoInterval</code>)</li>
45	<li><b>Create Resource:</b> Creates a library resource</li>	40	<li><b>Create Resource:</b> Creates a library resource</li>
Lines 70-76 Link Here
70	<li>Unified Transaction Semantics</li>	65	<li>Unified Transaction Semantics</li>
71	<li>Undo/Redo management</li>	66	<li>Undo/Redo management</li>
72	<li>Multi-threaded access control</li>	67	<li>Multi-threaded access control</li>
73	<li>Management of logical resources persisted in multiple physical resources</li>
74	<li>Batch notification of events</li>	68	<li>Batch notification of events</li>
75	<li>Evaluation of live constraints</li>	69	<li>Evaluation of live constraints</li>
76	<li>Common read and write operations</li>	70	<li>Common read and write operations</li>

Lines 15-22 Link Here

(-)html/tutorials/msl/modelManagementTutorial.html (-190 / +4 lines)
15		15
16	<table border="0" cellspacing="8" cellpadding="0">	16	<table border="0" cellspacing="8" cellpadding="0">
17	<tr>	17	<tr>
18	<td>Version: 0.1</td>	18	<td>Version: 0.2</td>
19	<td>Date: June 08, 2005</td>	19	<td>Date: Dec. 28, 2005</td>
		20	<!-- Removed references to the Logical Resource API -->
20	</tr>	21	</tr>
21	</table>	22	</table>
22		23
Lines 28-34 Link Here
28	<li><a href="#intro">Introduction</a></li>	29	<li><a href="#intro">Introduction</a></li>
29	<li><a href="#editing_domain">Creating and Using an MSL Editing Domain</a></li>	30	<li><a href="#editing_domain">Creating and Using an MSL Editing Domain</a></li>
30	<li><a href="#making_changes">Making Changes to Resources</a></li>	31	<li><a href="#making_changes">Making Changes to Resources</a></li>
31	<li><a href="#logical">Working with Logical Resources</a></li>
32	<li><a href="#listeners">MSL Listeners</a></li>	32	<li><a href="#listeners">MSL Listeners</a></li>
33	<li><a href="#validation">Model Validation</a></li>	33	<li><a href="#validation">Model Validation</a></li>
34	<li><a href="#copy_paste">MSL Copy and Paste Support</a></li>	34	<li><a href="#copy_paste">MSL Copy and Paste Support</a></li>
Lines 44-50 Link Here
44	<p class="backto"><font size="-1">[<a href="#top">back to top</a>]</font></p>	44	<p class="backto"><font size="-1">[<a href="#top">back to top</a>]</font></p>
45		45
46	<p>	46	<p>
47	The Model Service Layer(MSL) provides a number of facilities to ease model management:	47	The Model Service Layer (MSL) provides a number of facilities to ease model management:
48	model modification semantics, uniform resource creation and loading, uniform listener	48	model modification semantics, uniform resource creation and loading, uniform listener
49	registration, batching of notifications, live validation with automatic modification	49	registration, batching of notifications, live validation with automatic modification
50	abandonment, copy/paste support, automated pathmap support and additional metamodel support.	50	abandonment, copy/paste support, automated pathmap support and additional metamodel support.
Lines 203-392 Link Here
203	editingDomain.saveResource(r1);	203	editingDomain.saveResource(r1);
204	</pre>	204	</pre>
205		205
206	<h2><a name="logical"></a>Working with Logical Resources</h2>
207
208	<p class="backto"><font size="-1">[<a href="#top">back to top</a>]</font></p>
209
210	<p>
211	The MSL's default resource implementation conforms to the
212	<a href="../../reference/api/common/org/eclipse/gmf/runtime/emf/core/resources/ILogicalResource.html"><code>ILogicalResource</code></a>
213	interface. This resource creates an in-memory logical view of an EMF tree
214	(or forest) structure that is persisted in multiple physical resources, all of
215	which are XMI-compliant. The central concept in the logical-to-physical mapping
216	of an MSL resource is the "separate" element. A separate elements is persisted
217	in a different, or separate, physical resource than its container.
218	</p><p>
219	To obtain a logical resource, use the editing domain to create a resource as
220	described <a href="#create_resource">above</a> and then get a view of it as
221	an <code>ILogicalResource</code>.
222	To store a model element in its own physical resource, just ask the logical
223	resource to separate it into a new resource on a URI of your choosing. Don't
224	forget to ask first whether it <i>can</i> be separated (the metamodel may
225	implement rules restricting what can be separated; see below):
226	</p>
227	<pre class="snippet">
228	Resource r1 =
229	editingDomain.createResource("file://c:/eclipse/workspace/aProject/test.rmplibrary",
230	RMPLibraryPackage.eINSTANCE.getLibrary());
231	ILogicalResource logical = editingDomain.asLogicalResource(r1);
232
233	// ... fill the resource with contents
234
235	EObject element = // ... find an element to be separated
236
237	if (logical.canSeparate(element)) {
238	try {
239	logical.separate(
240	element,
241	URI.createURI("file://c:/eclipse/workspace/aProject/test.sub1.rmplibrary"));
242	} catch (CannotSeparateException e) {
243	System.out.println("Could not separate the element: " + element);
244	e.printStackTrace();
245	}
246	}
247
248	editingDomain.saveResource(logical); // or logical.save(Collections.EMPTY_MAP);
249	</pre>
250	<p>
251	We now have one logical resource stored in two files.
252	</p><p>
253	Note the use of the <code>ILogicalResource MEditingDomain.asLogicalResource(Resource)</code>
254	method to obtain a view of an arbitrary resource as a logical resource. This is
255	necessary because the editing domain might actually instantiate any resource
256	implementation, not necessarily a logical resource, depending on the registered
257	resource factories. If the resource is not actually a logical resource, then
258	this method creates a wrapper that provides compatibility with the logical
259	resource API.
260	</p><p>
261	In the snippet above, we catch <code>CannotSeparateException</code> despite
262	being informed that the separation would be permitted because there may be
263	unexpected conditions that prevent the separation from succeeding (such as
264	incorrect file permissions). No attempt is made to actually persist the new
265	physical resource until the logical resource is saved, but a metamodel extension
266	might be proactive in checking even at this point whether certain I/O limitations
267	would be exceeded.
268	</p><p>
269	To do the inverse of a separation operation, we can <i>absorb</i> an element
270	from a separate resource into the same resource as its container:
271	</p>
272
273	<pre class="snippet">
274	if (logical.isSeparate(element)) {
275	try {
276	logical.absorb(element);
277	} catch (CannotAbsorbException e) {
278	System.out.println("Could not absorb the element: " + element);
279	e.printStackTrace();
280	}
281	}
282
283	editingDomain.saveResource(logical);
284	</pre>
285	<p>
286	Now, our logical resource is again stored in a single file. Note that the
287	<tt>test.sub1.rmplibrary</tt> file is not deleted, though it will be empty.
288	This simplifies comparing and merging changes with a source control repository.
289	Note also that, like separation, absorption can fail unexpectedly.
290	</p><p>
291	How does the MSL framework determine whether an element can be separated? By
292	default, any element of any EMF metamodel can be separated, unless it is a
293	root of the logical resource or has already been separated. However, a metamodel
294	provider or an application may for some reason want to restrict the elements
295	that may be separated. This is accomplished by registering a policy on the
296	<a href="../../reference/extension-points/org_eclipse_gmf_runtime_emf_core_resourcePolicies.html"><code>org.eclipse.gmf.runtime.emf.core.resourcePolicies</code></a>
297	extension point:
298	</p>
299	<pre class="snippet">
300	<extension
301	point="org.eclipse.gmf.runtime.emf.core.resourcePolicies">
302	<policy
303	class="org.eclipse.gmf.examples.runtime.emf.resources.LibraryResourcePolicy"
304	nsURI="http:///com/ibm/xtools/emf/metamodel/example/pde/rmplibrary.ecore/1.0.0"/>
305	</extension>
306	</pre>
307	<p>
308	The policy implements the
309	<a href="../../reference/api/common/org/eclipse/gmf/runtime/emf/core/resources/ILogicalResourcePolicy.html"><code>ILogicalResourcePolicy</code></a>
310	interface, usually by extending the <code>AbstractLogicalResourcePolicy</code>
311	class. Our example allows only libraries to be separated:
312	</p>
313	<pre class="snippet">
314	public class LibraryResourcePolicy
315	extends AbstractLogicalResourcePolicy {
316
317	public boolean canSeparate(ILogicalResource resource, EObject eObject) {
318	return eObject instanceof Library;
319	}
320	}
321	</pre>
322	<p>
323	Policies can also suggest default URIs for new physical resources according to
324	some application-specific naming system, implement extra checks when clients
325	perform separations or absorptions, etc.
326	</p><p>
327	By default, logical resources initially load only the root resource (corresponding
328	to the logical URI) and automatically load other resources as they are needed
329	by access of containment references or proxy resolution. The <code>ILogicalResource</code>
330	interface defines load options to disable incremental loading or to initially
331	load the entire logical resource contents. Automatic incremental loading of
332	separate objects from containment references requires a custom <code>EList</code>
333	that loads the necessary resources on demand. Two convenient implementations
334	are provided by the MSL for metamodels to use in place of the
335	<code>EObjectContainmentEList</code> and <code>EObjectContainmentWithInverseEList</code>
336	classes. However, it may be necessary for a metamodel to be deployable without
337	the MSL, in a "pure EMF" configuration. To address this need, the
338	<code>resourcePolicies</code> extension point allows the registration of
339	an <code>EFactory</code> that creates alternative <code>*Impl</code> classes
340	that use these special lists, to be deployed only in MSL configurations:
341	</p>
342	<pre class="snippet">
343	<extension
344	point="org.eclipse.gmf.runtime.emf.core.resourcePolicies">
345	<efactory
346	class="org.eclipse.gmf.examples.runtime.emf.resources.LoadingRMPLibraryFactoryImpl"
347	nsURI="http:///com/ibm/xtools/emf/metamodel/example/pde/rmplibrary.ecore/1.0.0"/>
348	</extension>
349	</pre>
350	<p>
351	The MSL framework will use this factory instead of the default when loading
352	a logical resource; it does not need to be used by clients to create new objects.
353	In our example, only libraries can be separated and only libraries can contain
354	other libraries, so our factory simply creates a specialization of the default
355	<code>LibraryImpl</code> class:
356	</p>
357	<pre class="snippet">
358	public class LoadingRMPLibraryFactoryImpl
359	extends RMPLibraryFactoryImpl {
360
361	public Library createLibrary() {
362	return new LoadingLibraryImpl();
363	}
364
365	public EPackage getEPackage() {
366	return RMPLibraryPackage.eINSTANCE;
367	}
368	}
369
370	class LoadingLibraryImpl
371	extends LibraryImpl {
372
373	public LoadingLibraryImpl() {
374	super();
375
376	// use the custom containment-with-inverse list to perform automatic
377	// loading of contained elements in this feature. This pre-empts
378	// the superclass's lazy initialization of this list
379	branches = new EObjectContainmentWithInverseLoadingEList(
380	Library.class, this, RMPLibraryPackage.LIBRARY__BRANCHES,
381	RMPLibraryPackage.LIBRARY__PARENT_BRANCH);
382	}
383	}
384	</pre>
385	<p>
386	Note how we only concern ourselves here with overriding the implementation of
387	those features that will be able to contain separate elements.
388	</p>
389
390	<h2><a name="listeners"></a>MSL Listeners</h2>	206	<h2><a name="listeners"></a>MSL Listeners</h2>
391		207
392	<p class="backto"><font size="-1">[<a href="#top">back to top</a>]</font></p>	208	<p class="backto"><font size="-1">[<a href="#top">back to top</a>]</font></p>
Lines 755-762 Link Here
755	<li>Registered the MSL resource factory for the .rmplibrary file extension</li>	571	<li>Registered the MSL resource factory for the .rmplibrary file extension</li>
756	<li>Made changes to MSL resources using an undo interval and a write action</li>	572	<li>Made changes to MSL resources using an undo interval and a write action</li>
757	<li>Undid and redid the changes made during an undo interval</li>	573	<li>Undid and redid the changes made during an undo interval</li>
758	<li>Created logical resources consisting of multiple files</li>
759	<li>Customized the management of logical resources for library models</li>
760	<li>Registerd an MSL listener that informed us whenever a resource was dirtied</li>	574	<li>Registerd an MSL listener that informed us whenever a resource was dirtied</li>
761	<li>Learned how live validation can be used to enforce resource integrity during write actions</li>	575	<li>Learned how live validation can be used to enforce resource integrity during write actions</li>
762	<li>Learned how to perform batch validation when using MSL</li>	576	<li>Learned how to perform batch validation when using MSL</li>