xArchFlatProxy Overview

The XArchFlatInterface is a distributable interface that provides additional low-level functionality that is not available when using the xArch/xADL 2.0 Data Binding Library directly. However, it uses strings to specify (indirectly) method calls. Thus, errors that are normally detected by the compiler when type-checking (when using the native Data Binding Libray interface) will show up only at run-time as exceptions (when using the XArchFlatInterface).

This can make it difficult to manage source code that takes advantage of the XArchFlatInterface. It can be especially difficult to maintain source code so that it adheres to changes in one of the Data Binding Library's underlying XML schemas. Recompiling will not indicate that a removed method no longer exists, or that method signatures have changed. In addition, using the XArchFlatInterface prevents one from using the code assist features (e.g., AutoComplete) that are available in many modern integrated development environments.

XArchFlatProxy addresses these problems by providing a layer on top of the XArchFlatInterface that exposes interfaces nearly identical to those exposed by the xArch/xADL 2.0 Data Binding Library (e.g., IComponent). Thus, calls using the XArchFlatProxy mechanism will appear (and compile) like calls made to the data binding library directly. In reality, however, these calls will be dynamically translated to XArchFlatInterface calls "under the covers." As such, this allows you to combine the ease of use of the data binding library's interface with the distributability and loose coupling provided by the XArchFlatInterface.

---

Limitations

XArchFlatProxy is somewhat more limited than using the data binding library or the XArchFlatInterface directly, namely:

• XArchFlatProxy users cannot directly add themselves as XArchListeners and receive XArchEvents.
• XArchFlatProxy users cannot take advantage of the transaction mechanism provided by the XArchFlatTransactionsInterface.
• XArchFlatProxy users cannot take advantage of the bulk query mechanism provided by the XArchFlatInterface.

Let's look at how to use XArchFlatProxy. Using this mechanism imposes certain minor constraints on your code:

1. You must access documents using data binding interfaces (e.g., IDescription), not implementation types (e.g., DescriptionImpl). (NB: You shouldn't be using Impl classes in any case)
2. Create documents and contexts through the XArchFlatProxyImplementation object rather than the now-deprecated XArchUtils mechanism, or the DOM-based DOMBasedXArchImplementation, or direct context constructors (new TypesContext(...)).

Note: even if you used interfaces before, the latest version of Apigen creates additional interfaces to address objects (e.g., contexts) that previously had none.

---

Working with xArchFlatProxy

A program that was previously written to use the DOM-based Data Binding Library should be modified to:

1. Use the proxied version of the IXArchImplementation;
2. Use interfaces (if it did not already do so); and
3. Create contexts and manipulate documents using the IXArchImplementation.

Below is an example piece of code before modification.

  //Create a DOM-based IXArchImplementation
  IXArchImplementation xArchImplementation =
    XArchUtils.getDefaultXArchImplementation();

  //Create a new xArch element (i.e. a xADL 2.0 document)
  IXArch xArch = xArchImplementation.createXArch();

  //Create types and instance contexts
  InstanceContext instance = new InstanceContext(xArch);
  TypesContext types = new TypesContext(xArch);

  //Create a component and description
  ComponentImpl component = types.createComponent();
  component.setId("example_component_id");

  DescriptionImpl description = types.createDescription();
  description.setValue("Example Component Description");
  component.setDescription(description);

Modifiying the code to use interfaces and create contexts using the IXArchImplementation produces the following code (changes are in bold, note the additional "I" in front of the context types to indicate access of contexts through their interface).

  //Create a DOM-based IXArchImplementation
  IXArchImplementation xArchImplementation =
    XArchUtils.getDefaultXArchImplementation();

  //Create a new xArch element (i.e. a xADL 2.0 document)
  IXArch xArch = xArchImplementation.createXArch();

  //Create types and instance contexts
  IInstanceContext instance =
    (IInstanceContext) xArchImplementation.createContext("instance");
  ITypesContext types =
    (ITypesContext)xArchImplementation.createContext("types");

  //Create a component and description
  IComponent component = types.createComponent();
  component.setId("example_component_id");

  IDescription description = types.createDescription();
  description.setValue("Example Component Description");
  component.setDescription(description);

Now, in order to use the Data Binding Library interfaces by proxy across an instance of XArchFlatInterface, simply call XArchFlatProxyUtils.getXArchImplementation(XArchFlatInterface xArch)

After you have proxied one XArchFlatInterface, all elements returned by the proxied object will automatically be proxied on your behalf. To modify the code above so that it works on an instance of XArchFlatInterface would require the following changes (in bold):

  //Create (or acquire) an instance of XArchFlatInterface
  XArchFlatInterface xArchFlat = new XArchFlatImpl();

  //Create an XArchFlatProxy-based IXArchImplementation
  IXArchImplementation xArchImplementation =
    XArchFlatProxyUtils.getXArchFlatProxyImplementation(xArchFlat);

  //Create a new xArch element (i.e. a xADL 2.0 document)
  IXArch xArch = xArchImplementation.createXArch();

  //Create types and instance contexts
  IInstanceContext instance =
    (IInstanceContext) xArchImplementation.createContext("instance");
  ITypesContext types =
    (ITypesContext)xArchImplementation.createContext("types");

  //Create a component and description
  IComponent component = types.createComponent();
  component.setId("example_component_id");

  IDescription description = types.createDescription();
  description.setValue("Example Component Description");
  component.setDescription(description);

Note: Only one line had to be changed, the others were added to clarify where the xArch instance came from. The rest of the code, unmodified, is operating over the XArchFlatInterface specified at the top of the code snippet.

---

Additional Capabilities

It's possible to proxy any XArchFlatInterface-style ObjRef into a Data Binding Library-style proxy as the following code example demonstrates:

  //Modify the description of the component in the examples above
  XArchFlatInterface xArchFlat = ...;
  ObjRef xArchRef = ...;
  ObjRef componentRef = xArchFlat.getByID(xArchRef, "example_component_id");
  ObjRef descriptionRef = xArchFlat.get(componentRef, "Description");

  //Proxy just the description and change it through XArchFlatProxy
  IDescription desc = (IDescription) XArchFlatProxyFactory.proxy(xArchFlat,
    descriptionRef);
  desc.setValue("Changed Component Description");

  //Print the description through XArchFlatInterface
  System.err.println(xArchFlat.get(descriptionRef, "Value"));
  // prints "Changed Component Description"

---

That's it!

Additional questions about the XArchFlatProxy mechanism should be sent to Scott A. Hendrickson.

---