API rules of engagement
- Only the APIs exposed in the javadoc reference are supported for programming
unless otherwise noted in the API documentation. The APIs in the javadocs
are stable and will not be removed across version boundaries. CARMA APIs
may be deprecated in future releases but should continue to be available and
usable by programmers in the future as defined by the documentation. Other
APIs may be found in the CARMA plug-ins but should be considered unsupported
and subject to change in future releases.
- The CARMA model APIs (com.ibm.carma.model package) are meant to be read-only from the programmer’s point of view, e.g., the
programmer should not attempt to create/add/move items in the CARMA model
manually. The objects in the hierarchy are meant to be updated through the refreshXXX() and createXXX() methods.
Model object creation outside of using API methods is not supported. If
model objects are created outside of using API methods then inconsistencies
may arise.
- All repository resource lists in the model are associated with a filter
string. The default filter string is “*”.
- Most CARMA model methods require the connection to the CARMA host to be
active when the method is executed. If the connection is not active then
a com.ibm.carma.transport.NotConnected exception is thrown.
- CARMA methods which need to activate the CARMA host connection have an org.eclipse.core.runtime.IProgressMonitor parameter
in the method signature. In order to cancel execution of the method we respect
the IProgressMonitor.isCancelled() method which is checked
during long-running method execution.
- The CARMA model serves as a cache of data for the CARMA hierarchy. It
is the responsibility of the programmer to keep the cache fresh using the refreshXXX() methods
on the model.
- The CARMA model cache must be initialized. If a portion of the CARMA
hierarchy which is not cached is accessed then a com.ibm.carma.transport.NotSynchronizedException is
thrown. To repair the exception execute a refreshXXX() method
on the object.
- The objects in the CARMA Model cache are available when disconnected from
the CARMA host. The CARMA host needs to be actively connected in order to
execute methods against the cache objects which access the CARMA host.
- Model changes are communicated out to listeners via notification. The
notification goes out to any adapter listening to the model object. Listeners
should be added to the model using a class which extends org.eclipse.emf.common.notify.Adapter.
This is an Eclipse Modeling Framework (EMF) notification method. Please
reference the EMF documentation for more information on Adapter notification.
- The default CARMA UI (including the externalized com.ibm.carma.ui.* APIs) use a combination of actions and jobs to execute methods
on the CARMA model. The Action (extending org.eclipse.ui.IAction or org.eclipse.ui.IActionDelegate)
is responsible for gathering the needed data to execute the model method.
The gathered data is handed off to a CARMA UI job, which is scheduled to
execute in the background when resources are available. If the model method
cause updates to the CARMA hierarchy then notifications are sent from the
model to listeners which update the UI as needed.
|
This information center is powered by Eclipse technology. (http://www.eclipse.org)