Design-Remote API

Overview

A significant difference in approach was the initial approach to expose the Local interfaces nearly completely. In this second go there is a goal to provide a smaller set of Remote interfaces that remain robust yet are easier to use for the vast majority of integration use cases. It will de-emphasize administration and focus on operational aspects of integration. This set of remopte interfaces must support the CLI, as well as support as many of our known use cases as possible. A more general goal is to be able to build powerful applications, both automation and GUI oriented, on this set of services. Although, it is not the goal to be able to implement the full JON GUI on this set of services.
These remote interfaces will be made available via JBoss Remoting for Java clients, and JAX-WS (JBossWS) for non-Java clients (although nothing prevents a Java WS client as well, it's just not obvious what the need would be given JBoss remoting).

Approach and Conventions

XxManagerRemote and XxManagerLocal interfaces will be implemented by the same impl XxManagerBean
- Utilize the current impls while providing a more consistent, convenient, and cohesive remote interface.
- Current locals have a lot of specific support for RHQ and lack consistency due to organic growth
Simplify API by providing simple services complemented by rich, multi-purpose counterparts for complex needs
Prefer paginated services
Other than login specific services, all services supply logged-in Subject as initial parameter for authorization
Carefully consider the needs for Administration services
- Judiciously provide CRUD; I expect that certain Add/Create services will be needed. Not sure of the use cases. Delete/Purge probably less so.
Simple getters
- Typically Provide getter by Id
- Will not allow for optional data
- To get optional data use 'find' or make a follow-on request for that specific data (if the service exists)
Convenience routines
- Be very judicious since we can't predict what will be generally convenient
- Only add if currently supported in SLSB and obviously generally useful
- rich find is always possible
getAll as a standard convenience service
- Rejected - too unconstrained
Avoid constructs tied to our UI implementation
- e.g. don't expose things like: List<AvailabilityPoint> getAvailabilityPointsForResourceGroup(...)
Find Criteria
- takes the entity and for supported fields, uses set values as search criteria
- must be jdoc'd to explicitly define supported search criteria (fields, values (explicit, pattern, etc)
Optional Data
- Allows the caller to specify (normally lazily loaded) data to be optionally returned.
- Provides a consistent way to provide deterministic results
- Embedded in PageControl with vararg setter
- an Enum defined by the relevant remote interface of supported data
Ordering results
- Required for all PageControlled queries
- Will require us to consolidate field references across the query base
Objects or primitives (Integer or ints)
- no real opinion, using primitives
Exceptions
- Most remote services will throw a checked exception
- One of the following RHQ Exceptions Create/Delete/Fetch/Update/Login/Deploy
- Since Local and Remote interface have single imple they may share entry points, so no remote-specific exceptions
- ensure as we go that the impls are actually handling/throwing exceptions as consistently as possible
No overloading, use different service names for each service within a manager.
- More clear for various remote API invocation types
- Better for CLI auto-complete

Planned Remotes

Use Case valueY(in)/#(in, use case number)/N(out)/M(maybe, proposed but no current use case)/
Status value = P(pass)/F(fail) blank indicates untested

Remote Interface	Review	Test Status	Service

AlertDefinitionManagerRemote

Use Case	Status	Service
		AlertDefinition getAlertDefinition(Subject sessionSubject, int alertDefinitionId ) throws FetchException
		PageList<AlertDefinition> findAlertDefinitions(Subject sessionSubject, AlertDefinition criteria PageControl pc ) throws FetchException Optional Data none Criteria id name (pattern) resourceId resourceType

AlertManagerRemote

Use Case	Status	Service
2		PageList<Alert> findAlerts(Subject sessionSubject, Alert criteria, int[] resourceIds, long beginTime, long endTime, PageControl pc) throws FetchException Optional Data conditionLogs (Set<AlertConditionLog>) Criteria id priority definitionId

AvailabilityManagerRemote

Use Case	Status	Service
		PageList<Availability> getAvailabilityForResource(Subject sessionSubject, int resourceId, PageControl pc) throws FetchException
		Availability getCurrentAvailabilityForResource(Subject sessionSubject, int resourceId) throws FetchException

CallTimeDataManagerRemote

Use Case	Status	Service
		PageList<CallTimeDataComposite> getCallTimeDataForResource(Subject sessionSubject, int measurementScheduleId, long beginTime, long endTime, PageControl pageControl) throws FetchException
		PageList<CallTimeDataComposite> getCallTimeDataForCompatibleGroup(Subject sessionSubject, int groupId, int measurementDefinitionId, long beginTime, long endTime, PageControl pageControl) throws FetchException

ChannelManagerRemote

Use Case	Status	Service
8		void addPackageVersionsToChannel(Subject sessionSubject, int channelId, int[] packageVersionIds) throws UpdateException
8		Channel createChannel(Subject sessionSubject, Channel channel) throws CreateException
8		void deleteChannel(Subject sessionSubject, int channelId) throws DeleteException
8		Channel getChannel(Subject sessionSubject, int channelId) throws FetchException
8		PageList<Channel> findChannels(Subject sessionSubject, Channel criteria, PageControl pc) throws FetchException Optional Data channelPackageVersions (Set<ChannelPackageVersion>) Criteria id
8		PageList<PackageVersion> findPackageVersionsInChannel(Subject sessionSubject, int channelId, PackageVersion criteria, PageControl pc) throws FetchException Optional Data extraProperties (Configuration) channelPackageVersions (Set<ChannelPackageVersion>) productVersionPackageVersions (Set<ProductVersionPackageVersion>) Criteria id name (filter)
8		Channel updateChannel(Subject sessionSubject, Channel newChannel) throws UpdateException

ConfigurationManagerRemote

Enum ConfigurationType
CURRENT
LIVE

Use Case	Status	Service
		AggregatePluginConfigurationUpdate getAggregatePluginConfigurationUpdate(Subject sessionSubject, int configurationUpdateId) throws FetchException will load configurationUpdates (List<PluginConfigurationUpdate>)
		AggregateResourceConfigurationUpdate getAggregateResourceConfigurationUpdate(Subject sessionSubject, int configurationUpdateId) throws FetchException will load configurationUpdates (List<ResourceConfigurationUpdate>)
		Configuration getConfiguration(Subject sessionSubject, int configurationId) throws FetchException
3		Configuration getPluginConfiguration(Subject sessionSubject, int resourceId, ConfigurationType type) throws FetchException
3		Configuration getResourceConfiguration(Subject sessionSubject, int resourceId, ConfigurationType type) throws FetchException
		PluginConfigurationUpdate getLatestPluginConfigurationUpdate(Subject sessionSubject, int resourceId) throws FetchException
		PluginConfigurationUpdate getLatestResourceConfigurationUpdate(Subject sessionSubject, int resourceId) throws FetchException
3		boolean isResourceConfigurationUpdateInProgress(Subject sessionSubject, int resourceId) throws FetchException
		boolean isAggregateResourceConfigurationUpdateInProgress(Subject sessionSubject, int resourceGroupId) throws FetchException
		int scheduleAggregatePluginConfigurationUpdate(Subject sessionSubject, int compatibleGroupId, Map<Integer, Configuration> newResourcePluginConfigurationMap) throws UpdateException
		int scheduleAggregateResourceConfigurationUpdate(Subject sessionSubject, int compatibleGroupId, Map<Integer, Configuration> newResourceConfigurationMap) throws UpdateException
3		PluginConfigurationUpdate updatePluginConfiguration(Subject sessionSubject, int resourceId, Configuration newConfiguration) throws UpdateException
3		ResourceConfigurationUpdate updateResourceConfiguration(Subject sessionSubject, int resourceId, Configuration newConfiguration) throws UpdateException

ContentManagerRemote

Use Case	Status	Service
8		PackageVersion createPackageVersion(Subject sessionSubject, String packageName, int packageTypeId, String version, int architectureId, InputStream packageBitStream) throws CreateException
8		void deletePackages(Subject sessionSubject, int resourceId, int[] installedPackageIds, String requestNotes) throws DeleteException
8		void deployPackages(Subject sessionSubject, int[] resourceIds, int[] packageVersionIds) throws DeployException

EventManagerRemote

Use Case	Status	Service
5		PageList<EventComposite> getEventsForResource(Subject sessionSubject, int resourceId, long begin, long end, EventSeverity severity, String source, String detail, PageControl pc) throws FetchException
		PageList<EventComposite> getEventsForAutoGroup(Subject sessionSubject, int groupId, long begin, long end, EventSeverity severity, int parentId, String source, String detail, PageControl) throws FetchException
		PageList<EventComposite> getEventsForCompGroup(Subject sessionSubject, int groupId, long begin, long end, EventSeverity severity, int eventId, String source, String detail, PageControl pc) pc) throws FetchException
		EventSeverity[] getSeverityBuckets(Subject sessionSubject, int resourceId, long begin, long end, int numBuckets) throws FetchException
		EventSeverity[] getSeverityBucketsForAutoGroup(Subject sessionSubject, int parentId, long begin, long end, int numBuckets) throws FetchException
		EventSeverity[] getSeverityBucketsForCompGroup(Subject sessionSubject, int groupId, long begin, long end, int numBuckets) throws FetchException
		PageList<EventComposite> findEvents(Subject sessionSubject, long begin, long end, Event criteria, PageControl pc) throws FetchException Criteria id (event.id) Severity (event.severity) Detail (event.detail)

MeasurementBaselineManagerRemote

Use Case	Status	Service
		List<MeasurementBaseline> getBaselinesForResource(Subject sessionSubject, int resourceId ) throws FetchException

MeasurementDataManagerRemote

Use Case	Status	Service
		MeasurementAggregate getAggregate(Subject sessionSubject, int scheduleId, long startTime, long endTime) throws FetchException
4		List<MeasurementDataTrait> getTrait(Subject sessionSubject, int resourceId, int definitionId) throws FetchException
4		List<MeasurementDataTrait> getCurrentTraits(Subject sessionSubject, int resourceId) throws FetchException
4		Set<MeasurementData> getLiveData(Subject sessionSubject, int resourceId, int[] definitionIds) throws FetchException
		List<List<MeasurementDataNumericHighLowComposite>> getDataForCompatibleGroup(Subject sessionSubject, int groupId, int definitionId, long beginTime, long endTime, int numPoints, boolean groupAggregateOnly) throws FetchException
4		List<List<MeasurementDataNumericHighLowComposite>> getDataForResource(Subject sessionSubject, int resourceId, int[] definitionIds, long beginTime, long endTime, int numPoints) throws FetchException

MeasurementDefinitionManagerRemote

Use Case	Status	Service
		MeasurementDefinition getMeasurementDefinition(Subject sessionSubject, int definitionId) throws FetchException
7		PageList<MeasurementDefinition> findMeasurementDefinitions(Subject sessionSubject, MeasurementDefinition criteria, PageControl pc) throws FetchException Optional Data resourceType (ResourceType) schedules (List<MeasurementSchedule>) Criteria id resourceType dataType scheduleIds (can we handle a list/IN in the generator?)

MeasurementProblemManagerRemote

Use Case	Status	Service
		PageList<ProblemResourceComposite> getProblemResources(Subject sessionSubject, long beginTime, int maxResources, PageControl pc) throws FetchException

MeasurementScheduleManagerRemote

Use Case	Status	Service
		void disableSchedules(Subject sessionSubject, int resourceId, int[] definitionIds ) throws UpdateException
		void disableSchedulesForCompatibleGroup(Subject sessionSubject, int groupId, int[] measurementDefinitionIds ) throws UpdateException

		void enableSchedules(Subject sessionSubject, int resourceId, int[] definitionIds ) throws UpdateException
		void enableSchedulesForCompatibleGroup(Subject sessionSubject, int groupId, int[] definitionIds ) throws UpdateException

		PageList<MeasurementScheduleComposite> getDefaultMeasurementSchedulesForResourceType(Subject subject, int resourceTypeId, PageControl pageControl)
		List<MeasurementSchedule> getMeasurementSchedulesByDefinitionIdAndResources(Subject subject, int definitionId, List<Resource> resources)
		PageList<MeasurementScheduleComposite> getMeasurementSchedulesForAutoGroup(Subject subject, int parentId, int childType, PageControl pageControl)
		public PageList<MeasurementScheduleComposite> getMeasurementSchedulesForCompatGroup(Subject subject, int groupId, PageControl pageControl)
		PageList<MeasurementScheduleComposite> getMeasurementSchedulesForResource(Subject subject, int resourceId, DataType dataType, PageControl pageControl)
		List<MeasurementSchedule> getSchedulesByIds(Subject subject, Collection<Integer> ids) added Subject param

OperationManagerRemote

Use Case	Status	Service
1		void cancelOperationHistory(Subject sessionSubject, int historyId, boolean ignoreAgentErrors)
1		void deleteOperationHistory(Subject sessionSubject, int historyId, boolean purgeInProgress)
1		void unscheduleResourceOperation(Subject sessionSubject, String jobId, int resourceId) throws UnscheduleException
		void unscheduleGroupOperation(Subject sessionSubject, String jobId, int resourceGroupId) throws UnscheduleException
		ResourceOperationSchedule scheduleResourceOperation(Subject sessionSubject, int resourceId, String operationName, long delay, long repeatInterval, int repeatCount, int timeout, Configuration parameters, String description) throws ScheduleException
		GroupOperationSchedule scheduleGroupOperation(Subject sessionSubject, int groupId, int[] executionOrderResourceIds,boolean haltOnFailure, String operationName, Configuration parameters, long delay, long repeatInterval, int repeatCount, int timeout, String description) throws ScheduleException
M		OperationHistory getOperationHistoryByHistoryId(Subject sessionSubject, int historyId)
M		OperationHistory getOperationHistoryByJobId(Subject sessionSubject, String historyJobId)
1		PageList<ResourceOperationHistory> findOperationHistories(Subject sessionSubject, ResourceOperationHistory criteria, PageControl pc) throws FetchException Criteria Status (ResourceOperationHistory.status) CreatedTime (ResourceOperationHistory.createdTime) jobName (ResourceOperationHistory.jobName) jobGroup (ResourceOperationHistory.jobGroup) ResourceId (ResourceOperationHistory.resource.id)

ResourceGroupManagerRemote

Use Case	Status	Service
		void addResourcesToGroup(Subject sessionSubject, int groupId, int[] resourceIds) throws UpdateException
		ResourceGroup createResourceGroup(Subject sessionSubject, ResourceGroup resourceGroup) throws CreateException
		void deleteResourceGroup(Subject sessionSubject, int groupId) throws DeleteException
		ResourceGroup getResourceGroup(Subject sessionSubject, int groupId) throws FetchException
		ResourceGroupComposite getResourceGroupComposite(Subject sessionSubject, int groupId) throws FetchException
		PageList<ResourceGroup> getResourceGroupsForRole(Subject sessionSubject, int roleId, PageControl pageControl) throws FetchException
		PageList<ResourceGroup> findResourceGroups(Subject sessionSubject, ResourceGroup criteria, PageControl pc) throws FetchException OptionalData - probable implicitResources (Set<Resource>) explicitResources (Set<Resource>) roles (Set<Role>) OptionalData - possible modifiedBy (Subject) operationHistories (List<GroupOperationHistory>) Criteria id groupCategory resourceCategory resourceType name (filter) resourceId
		PageList<ResourceGroupComposite> findResourceGroupComposites(Subject sessionSubject, ResourceGroup criteria, PageControl pc) throws FetchException OptionalData - same as findResourceGroups Criteria - same as findResourceGroups
		void removeResourcesFromGroup(Subject sessionSubject, int groupId, int[] resourceIds) throws UpdateException
		void setRecursive(Subject sessionSubject, int groupId, boolean isRecursive) throws UpdateException
		ResourceGroup updateResourceGroup(Subject sessionSubject, newResourceGroup) throws UpdateException

Notes:

Stuff not exposed at this time:
- group definition

ResourceManagerRemote

Use Case	Status	Service
		Resource getResource(Subject sessionSubject, int resourceId) throws FetchException
		List<Resource> getResourceLineage(Subject sessionSubject, int resourceId) throws FetchException
		PageList<Resource> findResources(Subject sessionSubject, Resource criteria, PageControl pc) throws FetchException OptionalData - probable agent (Agent) availability (List<Availability>) currentAvailability (ResourceAvailability) explicitGroups (Set<ResourceGroup>) implicitGroups (Set<ResourceGroup>) parentResource (Resource) pluginConfiguration (Configuration) productVersion (ProductVersion) resourceConfiguration (Configuration) resourceErrors (List<ResourceError>) resourceType (ResourceType) OptionalData - possible alertDefinitions (Set<AlertDefinitions>) contentServiceRequests (List<ContentServiceRequest>) createChildResourceRequests (List<CreateResourceHistory>) deleteResourceRequests (List<DeleteResourceHistory>) eventSources (Set<EventSource>) installedPackages (Set<InstalledPackage>) installedPackageHistory (List<InstalledPackageHistory>) modifiedBy (Subject) operationHistories (List<ResourceOperationHistory>) pluginConfigurationUpdates (List<PluginConfigurationUpdate>) resourceChannels (Set<ResourceChannel>) resourceConfigurationUpdates (List<ResourceConfigurationUpdate>) schedules (Set<MeasurementSchedule>) Criteria id String (Resource.description) Substring Match InventoryStatus (Resource.inventoryStatus) String (Resource.name) Substring Match ParentResource (Resource.parentResource.id) ResourceType (Resource.resourceType.id)
		PageList<Resource> findResourceChildren(Subject sessionSubject, Resource criteria, PageControl pc) throws FetchException OptionalData (for each child) Same as findResources Criteria (for child) id String (Resource.description) Substring Match InventoryStatus (Resource.inventoryStatus) String (Resource.name) Substring Match ResourceType (Resource.resourceType.id)
		void uninventoryResources(Subject sessionSubject, int[] resourceIds) throws DeleteException

RoleManagerRemote

Use Case	Status	Service
		Subject getRole(Subject sessionSubject, int roleId) throws FetchException
		PageList<Role> getSubjectAssignedRoles(Subject sessionSubject, int subjectId, PageControl pc ) throws FetchException
		PageList<Role> getSubjectUnassignedRoles(Subject sessionSubject, int subjectId, PageControl pc ) throws FetchException
		PageList<Role> findRoles(Subject sessionSubject, Role criteria, PageControl pc) throws FetchException
7		void addRolesToSubject(Subject sessionSubject, int subjectId, int[] roleIds) throws UpdateException
7		void addSubjectsToRole(Subject sessionSubject, int roleId, int[] subjectIds) throws UpdateException
7		void removeRolesFromSubject(Subject sessionSubject, int subjectId, int[] roleIds) throws UpdateException
7		void removeSubjectsFromRole(Subject sessionSubject, int roleId, int[] subjectIds) throws UpdateException
		void addRolesToGroup(Subject sessionSubject, int groupId, int[] roleIds) throws UpdateException
		void addGroupsToRole(Subject sessionSubject, int roleId, int[] groupIds) throws UpdateException
		void removeRolesFromGroup(Subject sessionSubject, int groupId, int[] roleIds) throws UpdateException
		void removeGroupsFromRole(Subject sessionSubject, int roleId, int[] groupIds) throws UpdateException

SubjectManagerRemote

Use Case	Status	Service
7		void changePassword(Subject sessionSubject, String username, String password) throws UpdateException
7		void createPrincipal(Subject sessionSubject, String username, String password) throws CreateException
7		Subject createSubject(Subject sessionSubject, Subject subject) throws CreateException
7		void deleteSubjects(Subject sessionSubject, int[] subjectIds) throws DeleteException
7		Subject getSubject(Subject sessionSubject, int subjectId ) throws FetchException
c		Subject getSubjectByName(Subject sessionSubject, String username ) throws FetchException
7		PageList<Subject> findSubjects(Subject sessionSubject, Subject criteria, PageControl pc) throws FetchException Optional Data roles (Set<Role>) Criteria id name (substring) firstName lastName emailAddress Sort name firstName lastName emailAddress
Y		boolean isLoggedIn(String username) throws FetchException
Y		Subject login(String username, String password) throws LoginException
Y		void logout(int sessionId)
7		Subject updateSubject(Subject sessionSubject, Subject newSubject) throws UpdateException

(Perhaps) notable exceptions to current API

AutoGroup
Group Definition
Permissions stuff
Resource HealthSummary stuff

Locals without planned remotes at this time:

Remote Interface	Notes
AffinityGroupManagerLocal	Not necessary, administration via GUI
AgentManagerLocal	Not necessary, administration via GUI
AgentStatusManagerLocal	Server impl, no exposure necessary
AlertConditionCacheManagerLocal	Server impl, no exposure necessary
AlertConditionLogManagerLocal	Server impl, no exposure necessary
AlertConditionManagerLocal	Not necessary to see alert conditions, just alert firings/history
AlertDampeningManagerLocal	Server impl, no exposure necessary
AlertNotificationManagerLocal	Not necessary to manipulate notifications
AlertTemplateManagerLocal	Not necessary to manipulate alert templates
AuthorizationManagerRemote	Logged in user will be denied services if they don't have the permissions necessary. Inspection of authorization information may not be needed.
CachedConditionManagerLocal	Server impl, no exposure necessary
CachedConditionProducerLocal	Server impl, no exposure necessary
CacheConsistencyManagerLocal	Server impl, no exposure necessary
ConfigurationMetadataManagerLocal	Do we need to be able to update config, leaning against...
ContentSourceManagerLocal	Not necessary, administration via GUI
ContentUIManagerLocal	Not necessary, administration via GUI
EmailManagerLocal	Server impl, no exposure necessary
EntityManagerFacadeLocal	Server impl, no exposure necessary
FailoverListManagerLocal	Not necessary, administration via GUI
GroupDefinitionExpressionBuilderManagerLocal	Not necessary, GUI support
GroupDefinitionManagerLocal	Not necessary, administration via GUI
MeasurementCompressionManagerLocal	Server impl, no exposure necessary
PartitionEventManagerLocal	Not necessary, administration via GUI
PerspectiveManagerLocal	Server impl, no exposure necessary
ProductVersionManagerLocal	Not necessary, administration via GUI
ResourceBossLocal	??? maybe need the ability to get an Inventory summary for the user ?
ResourceMetadataManagerLocal	Server impl, no exposure necessary
ResourceFactoryManagerLocal	Not necessary, administration via GUI
SchedulerLocal	Server impl, no exposure necessary
ServerManagerLocal	Not necessary, administration via GUI
SystemManagerLocal	Server impl, no exposure necessary ??? getVersion?