Override Files Migration
Migration of override files
 

Remember this should be done after stepping up to VE 1.2 and must be done before VE 1.3 because the old file format will not be supported in VE 1.3.

Description


In VE 1.2 the override files have been migrated to the EMF API ChangeDescription classes instead of the previous internal Event classes. This will allow us to use API and to remove the internal event model.

The old event model will be supported in VE 1.2 but it will be removed in VE 1.3 so any existing override files should be converted as soon as possible after the first VE 1.2 driver is available. The new format is not supported on VE 1.1.0.1 or below.

The concept between the two is still the same. They both describe how to override the JEM model by adding or changing model objects. Let's take a simple example. This is the original format of the java.lang.Character override file (Character.override):

    <?xml version="1.0" encoding="UTF-8"?>
    <event:Add xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:org.eclipse.ve.internal.cde.decorators="http:///org/eclipse/ve/internal/cde/decorators.ecore"
        xmlns:event="event.xmi" 
     featureName="eAnnotations">
   <addedEObjects xsi:type="org.eclipse.ve.internal.cde.decorators:BasePropertyDecorator"
        cellEditorClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.CharJavaCellEditor:class"
        labelProviderClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.CharJavaLabelProvider"
      />
    </event:Add>

This is the converted format:

    <?xml version="1.0" encoding="UTF-8"?>
    <change:ChangeDescription xmlns:org.eclipse.ve.internal.cde.decorators="http:///org/eclipse/ve/internal/cde/decorators.ecore" 
         xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xmlns:change="http://www.eclipse.org/emf/2003/Change" xmi:version="2.0">
       <objectChanges key="X:ROOT#//@root">
      <value featureName="eAnnotations">
           <listChanges referenceValues="_eAnnotations"/>
         </value>
       </objectChanges>
    <objectsToAttach xmi:id="_eAnnotations" cellEditorClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.CharJavaCellEditor:class"
         labelProviderClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.CharJavaLabelProvider" 
         xsi:type="org.eclipse.ve.internal.cde.decorators:BasePropertyDecorator"/>
    </change:ChangeDescription>

The elements that coorespond with each other between the two types are shown with the image in both.

The old format said there was an Add event, to the feature named eAnnotations. What was added is in the addEObjects element. It added the BasePropertyDecorator.

The new format uses a ChangeDescription instead of an Add. In the old format there was one event per update. If there was more than one update, there would be multiple events in the root of the XMI document. In the new format all of the changes are grouped under one ChangeDescription. Under the change description would be listed all one objectChanges element for each target JEM object being changed. In this case we only have one objectChanges. The key is the URI of the object to be changed. In our case we provide a special URI, "X:ROOT#//@root". This special root says that the target is the JEM class that this file is being loaded for. In this case it will reference the java.lang.Character JEM class. We use this special format so that it will be unique and can be found without ever being mistaken for a true URI.

So the objectChanges here contains a value element for each feature that will be changed for this target object. In our case we have one for the feature eAnnotations. Since eAnnotations is an isMany feature, we have to use the listChanges element to describe all of the objects that will be added to the eAnnotations. There would be one listChanges per object being added, in our case there is only one.

The listChanges points to the object being added. In this case it is an XMI:ID reference to an object later in the file, "_eAnnotations" in this case. The actual object being added is stored later in the change description. It is stored under the objectsToAttach element. We are attaching a BasePropertyDecorator. To allow simple forward reference from the listChanges we gave it the xmi:id="_eAnnotations" attribute setting.

Here is a more complicated example. It is AbstractButton override file.

    <?xml version="1.0" encoding="UTF-8"?>
    <xmi:XMI xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:org.eclipse.ve.internal.cde.decorators="http:///org/eclipse/ve/internal/cde/decorators.ecore"
        xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore" xmlns:event="event.xmi">
   <event:Add  featureName="eAnnotations">
     <addedEObjects xsi:type="org.eclipse.ve.internal.cde.decorators:ClassDescriptorDecorator"
          labelProviderClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.DefaultLabelProviderWithNameAndAttribute:text"/>
      </event:Add>
   <event:Add  featureName="eStructuralFeatures">
     <addedEObjects xsi:type="ecore:EReference" name="mnemonic" unsettable="true">
          <eAnnotations xsi:type="org.eclipse.ve.internal.cde.decorators:BasePropertyDecorator"
            labelProviderClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.BeanCellRenderer:org.eclipse.ve.internal.jfc.beaninfo.MnemonicEditor"
            cellEditorClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.BeanFeatureEditor:org.eclipse.ve.internal.jfc.beaninfo.MnemonicEditor"/>
        </addedEObjects>
      </event:Add>      
    </xmi:XMI>


    <?xml version="1.0" encoding="UTF-8"?>
    <change:ChangeDescription xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore" xmlns:org.eclipse.ve.internal.cde.decorators="http:///org/eclipse/ve/internal/cde/decorators.ecore" xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:change="http://www.eclipse.org/emf/2003/Change" xmi:version="2.0">
       <objectChanges key="X:ROOT#//@root">
      <value featureName="eAnnotations">
           <listChanges referenceValues="_eAnnotations"/>
         </value>
      <value featureName="eStructuralFeatures">
           <listChanges referenceValues="_eStructuralFeatures"/>
         </value>
       </objectChanges>
    <objectsToAttach xmi:id="_eAnnotations" 
         labelProviderClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.DefaultLabelProviderWithNameAndAttribute:text" 
         xsi:type="org.eclipse.ve.internal.cde.decorators:ClassDescriptorDecorator"/>
    <objectsToAttach xmi:id="_eStructuralFeatures" name="mnemonic" unsettable="true" xsi:type="ecore:EReference">
         <eAnnotations cellEditorClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.BeanFeatureEditor:org.eclipse.ve.internal.jfc.beaninfo.MnemonicEditor" 
           labelProviderClassname="org.eclipse.ve.java.core/org.eclipse.ve.internal.java.core.BeanCellRenderer:org.eclipse.ve.internal.jfc.beaninfo.MnemonicEditor" 
           xsi:type="org.eclipse.ve.internal.cde.decorators:BasePropertyDecorator"/>
       </objectsToAttach>
    </change:ChangeDescription>
Migration Instructions

These instructions will migrate the override files to the new format. Basically what will be done is a migration feature will be installed into the development Eclipse (the one where the overrides files are being developed), the migration is executed, and then migration feature is uninstalled.

To install migration feature:

  1. Download the feature zip (migratesite.zip).
  2. Bring up the Eclipse IDE and select Help->Software Updates->Find and Install->Search for New Features
  3. Select the "New Archived Site" button and select the migratesite.zip file that was downloaded above.
  4. Select the "Eclipse.org" site and the "migratezip" site and hit the Finish button, select the appropriate mirror.
  5. When it comes back, select "migratesite" and hit the "Select Required" button.
  6. Then complete the installation with Next button.

Now to perform the migration, for each override directory in development, select the directory, bring up the popup menu and selec the "Migrate Override Files" button. This will perform the migration. It will migrate all of those that it can understand. It will bring up an error dialog listing what was wrong with any it couldn't convert. These will need to be fixed if it was syntax errors, or they will need to be converted by hand. The migration facility only understands Add, AddMany, and Set events. Other event types are not understood. They however should be rare if any. None of VE itself has used anything but Add, AddMany, and Set. If there are other types, please contact the VE mailing list for instructions.

Now that they are converted the migration feature can be uninstalled and removed:

  1. Select Help->Software Updates->Manage Configuration
  2. Select the Migrate Overrides feature, and then select the "disable" link from the Available Tasks list on the right window
  3. After restarting, go back to Manage Configuration, and select the Show Disabled Features
    ( ) toolbar item.
  4. Select the Migrate Overrides feature and then select the "uinstall" link from the Available Tasks list on the right window.

It should now be migrated and the feature uninstalled.