---

Visual Mobility Designer - Modifying DesignDocument and DesignComponent - Read/Write access.

Abstract

To read or write data from the Document it's necessary to obtain read/write access to the Document. Core of the Read/Write API is Transaction Manager described below. Transaction Manager is part of the VMD Model API.

Core functionality - Transaction Manager

A document will not be possible to read/write without read/write access on Transaction Manager of a document. TransactionManager class manages a transactional access to a document. If developer wants execute a code which reads or writes to a document or its components than has to use TransactionManager and call readAccess or writeAccess method. A parameter is a Runnable which will be executed with read/write access. It uses the NetBeans MUTEX class. Therefore it allows multiple reads and just a single write access at the same time. When a read or a write access is granted, it automatically waits for a read access on descriptor registry.

Using Transaction Manager

Read access - Reading DesignComponent properties (example)

In this example custom components developer reads one of the property of the DesignComponent instance.

private DesignDocument document;
private DesignComponent component;

...
    //Getting TransactionManager instance
    TransactionManager manager = document.getTransactionManager();
    
    //Obtaining document read access
    manager.readAccess(new Runnable() {
        public void run() {
                String propertyName = "Title";

                //Reading component's Title property
                String titleName = component.readProperty(propertyName);
        }
    });
 
...

Write access - Writing DesignComponent properties (example)

In this example custom components developer writes new PropertyValue to the one of the property of the DesignComponent instance.

private DesignDocument document;
private DesignComponent component;

...
    //Getting TransactionManager instance
    TransactionManager manager = document.getTransactionManager();
    
    //Obtaining document write access
    manager.writeAccess(new Runnable() {
        public void run() {
                String propertyName = "Title";
                PropertyValue newTitleValue = MidpTypes.createStringValue("My New Title");

                //Writing new value the component's Title property
                component.writeProperty(propertyName, newTitleValue);
        }
    });
 
...

Types of transaction managers

This section is not important for "regular" custom components developers. All DesignDocument read/write transactions are handled transparently by TransactionManager and NB MUTEX (underneath) thats why it is not necessary for most of the developers to read this section. There are 3 types of transaction managers implemented by Mutex. For prevent deadlocks there is a defined order of accesses/locks:

• GlobalDescriptorRegistry access
• DescriptorRegistry access
• Document access

You cannot get an access if you do not have previous ones.

On GlobalDescriptorRegistry.refresh:

• GlobalDescriptorRegistry.writeAccess
  • refresh global CDs (parentDescriptor, properties)
    • for each DescriptorRegistry
      • DescriptorRegistry.writeAccess
        • • refresh project CDs (parentDescriptor, properties)
          • for each document
            • document.writeAccess
              • refresh all components (descriptor, property values, presenters)

On Registry.refresh:

• GlobalDescriptorRegistry.readAccess
  • DescriptorRegistry.writeAccess
    • refresh project CDs (parentDescriptor, properties)
    • for each document
      • • document.writeAccess
        • refresh all components (descriptor, property values, presenters)

On Document.read:

• GlobalDescriptorRegistry.readAccess
  • DescriptorRegistry.readAccess
    • document.readAccess
      • document.read

On Document.write:

• GlobalDescriptorRegistry.readAccess
  • DescriptorRegistry.readAccess
    • document.writeAccess
      • document.write
      • while document is changed
        • • document.fireGroupEvent
            • presenters can do document.write

On Document.loading:

• GlobalDescriptorRegistry.readAccess
  • DescriptorRegistry.writeAccess
    • assert CDs - if a CD (which is required by the document is not in DescriptorRegistry, than try to load it from project).
  • DescriptorRegistry.readAccess
    • document.writeAccess
      • document.load
• report errors

This prevent other documents from freezing when one document is loading because it requires DescriptorRegistry.writeAccess for a time period which is really necessary.

Now if you request access, you have to supply a Runnable with the code. For that purpose an annotations could be used. The code will be in a method and the method will have an annotation describing which Mutex and which access this method request. All the sources has to be processed by APT. ?It is possible to modify just final class file and do not modify the line numbers, variable, scope visibility to fully allow using debugger

contact: Karol Harezlak