Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 2 Concepts : Cross-Resource References

Cross-Resource References
The Business Studio workspace acts as a container for resources such as projects, folders, and files, each of which corresponds to a directory or file in the operating system’s underlying file system. Workspace files can contain models (such as forms or business object models), which are comprised of model elements (such as panes and controls or classes and properties).
A form can refer to model elements in other resources in the Business Studio workspace, for example:
These references are often many-to-many, with one form referencing many external model elements and resources, each of which could potentially be referenced from multiple forms, business object models, processes and so on. These external references are known as cross-resource references.
Since the referenced model elements reside in independently modifiable files such references are susceptible to breakage if proper working procedures are not observed. When Business Studio detects breakages, it creates unresolved reference problem markers on the referencing forms.
This section talks about the different breakage mechanisms and the quick fixes available to resolve the problem markers.
Breakage Mechanisms
There are several ways in which a cross-resource references can be broken. Some examples are listed below:
When such changes are made using Business Studio, it attempts to prevent reference breakage by cascading such updates through all references. For example:
We now discuss some breakage scenarios in detail.
Deleting an Embedded Form
When an embedded form is deleted, you are offered a choice of either clearing the reference or retaining it.
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.
Figure 66 Clear Forms References Dialog
In this case, in future by default the references will all be cleared.
If necessary, you can still use the Preview button (as shown in Figure 67) and deselect any Clear forms references to deleted elements changes (as shown in Figure 68).
Figure 67 Delete Resources Dialog
Figure 68 Changes to be Performed Options
Please note, whether it is appropriate to clear or retain the references depends on your intentions.
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.
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.
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.
Quick Fixes
If a reference does get broken, Business Studio provides several quick fixes.
Reload the working copy quick fix removes stale unresolved reference problem markers.
Clear the reference quick fix simply clears the offending reference.
Repair the reference quick fix helps you to locate a suitable replacement model element.
Figure 69 Quick Fix Dialog
Reload the working copy - Quick Fix
This quick fix is used to remove the unresolved reference markers that can sometimes linger after the missing resource has been reinstated; this can sometimes happen during project import.
Clear the reference - Quick Fix
This quick fix can be applied to multiple unresolved reference problem markers simultaneously. It simply clears the offending references, which often places the referencing form model into an invalid state that is then reported by other problem markers. Such problems must then be fixed individually from within Form Designer.
Repair the reference - Quick Fix
This quick fix can only be applied to one unresolved reference problem marker at a time. It presents a dialog that lists all the possible model elements that could be used as a replacement for the missing referenced model element.
Figure 70 Repair Reference Dialog
The dialog has a set of filters that allow you to broaden or narrow the scope used to identify potential matches. When the dialog first comes up, all filters are active and no candidate items are visible. You can selectively disable filters to broaden the match scope until the list of candidates includes the desired replacement. The dialog remembers the filter settings. You can also type part of the target element name in the search box at the top the list will be filtered to show just the elements which match the search string. The filters are:
Project name
When this filter is active the list shows only matching items from the same project as that containing the originally referenced element. If no project of that name exists in the workspace you will have to deselect this filter to see anything at all.
File name
When this filter is active the list shows only items which reside in a file of the same unqualified name as that containing the originally referenced element. If no file of that name exists in the workspace you will have to deselect this filter to see anything at all.
Element type
When this filter is active the list shows only items which have the same type as the originally referenced element. For example, if the originally referenced element was a BOM class, the list will only show BOM classes. It is recommended to leave this filter enabled.
Element qualifier
When this filter is active the list shows only items which have the same qualifier name as the originally referenced element. For example, if the originally referenced element was a BOM type or property, the qualifier is the containing BOM package, so the list will only show BOM types or properties from a BOM package of the same qualified name as the original.
Element name
When this filter is active the list shows only items which have the same unqualified element name as the originally referenced element. For example, if the originally referenced element was a BOM type or property, the element name is the unqualified BOM type or property name (not the label).
Selecting the desired replacement and pressing the OK button closes the dialog and updates the form to point to the selected element, and the unresolved reference marker goes away. If the chosen item is in an unreferenced project the wizard requests permission to add a project reference.
Alternatively, pressing the Clear button closes the dialog and clears the unresolved reference – see the description for the Clear the reference quick fix.
 

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved