Breakage Mechanisms

There are several ways in which a cross-resource references can be broken.

Some examples are:

  • The referenced model element could be deleted
  • The referenced model element could be renamed
  • The element’s containing resource, folder or project could be deleted, renamed or moved elsewhere

When such changes are made using Business Studio, it attempts to prevent reference breakage by cascading such updates through all references. For example:

  • In the case of rename and move of an element or a containing resource, the references are all automatically updated to point to the new element name or workspace location.
  • In the case of deletion of a cross-referenced workspace resource, Business Studio presents a confirmation dialog offering the choice of clearing or retaining the references or cancelling the delete command. Clearing the references means that the connections between referenced and referencing elements are permanently severed and can only be restored manually.
    Note: In most cases such changes might prevent the referencing forms from working as intended and can cause other problem markers to appear if it places the forms into an invalid state.

We now discuss some breakage scenarios in detail.

Deletion of an Embedded Form

When an embedded form is deleted, you are offered a choice of either clearing the reference or retaining it.

  • Clearing the references to a deleted embedded form leaves the embedded form panes in an invalid state because they no longer point to a form to embed.
  • Conversely, retaining the references means that the referencing forms are left pointing at a resource or model element that no longer exists in the workspace, which will cause unresolved reference problem markers to appear.

The confirmation dialog presented by Business Studio when any form-referenced resource is deleted can be suppressed by selecting the Do not ask this question again check box on the Clear Forms References dialog.

In this case, in future by default all the references are cleared.

If necessary, you can still use the Preview button, and deselect any Clear forms references to deleted elements changes.

Whether it is appropriate to clear or retain the references depends on your intentions.

  • If you are deleting the resource because it is no longer required you should probably clear the references. In this case you would have to edit the forms to restore functionality.
  • If you are deleting the resource with the intention of reinstating it later, it is probably appropriate to retain the references. However, if you do this the form will be left in an unusable state and all manner of errors and problems would ensue if you tried to work with it.

Considerations for Making Changes to Business Studio Resources

Cross-resource references can also get broken by editing, renaming, moving or deleting resources without Business Studio’s knowledge, for example by changing the files directly in the underlying file system.

References can also get broken by making changes in one workspace and copying only a subset of the affected resources into another workspace.

Warning: These practices are strongly discouraged but unfortunately it may not always be obvious that a given action runs the risk of breaking a reference.

The basic principle is that related projects and the resources they contain are densely interconnected and should therefore be treated as an indivisible whole, managed exclusively from within Business Studio.

Problems with Business Studio Project Export/Import Wizard

Some development teams try to use the Eclipse File System or Business Studio Project Export/Import wizards to share projects or individual files and folders.

Warning: This practice is not recommended, as project-level exchange is at once too coarse-grained for convenient team development (where different developers make incremental changes to individual resources) and/or too fine-grained to maintain the integrity of cross-resource references and dependencies.

For example - if you move or rename a BOM file that is referenced from another project, this will update all forms references including those in referencing projects. If you then export just the project containing the changed BOM and import it to another workspace, the referencing forms in the target workspace will acquire unresolved reference problem markers because they will still be pointing to the old BOM file name or location.

If you have to use project export/import, you are recommended always to transfer a consistent set of projects, where all dependencies can be resolved from within the export/import location. Similarly, when importing projects, be sure to import all their dependencies as well.

Remember that you will be unable to import a project that already exists in the workspace and that the existing project may be inconsistent with the remaining visible incoming projects.

Advantages of Using Eclipse Team Providers

There is really only one satisfactory way for a development team to share resources, which is to place all projects under version control managed by an Eclipse team provider.

Business Studio bundles the Subclipse team provider for Subversion for this purpose. Many other version control systems have Eclipse team providers, which may or may not work well with Business Studio projects. Business Studio assumes optimistic version control concurrency semantics, so it does not support team providers which create read-only working copies or require an explicit working copy lock prior to editing (such as Perforce).

Even so, team members must take care not to do things which affect resources being modified by other team members – if this happens a merge conflict will result. The most reliable way to resolve a merge conflict is the ‘optimistic locking’ approach of rejecting one change set in its entirety then reapplying the rejected changes to the accepted change set. Otherwise, you will be faced with a tricky, error-prone textual merge of complex XML model files.