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.