To provide an initial set of remote services satisfying known or anticipated integration use cases.
Authenticated Access
Callers of the remote services must provide login information. The credentials must relate to a User already defined in the system and access/operations will be constrained given the granted permissions and roles for that user. The remote services will permit no more than what could similarly be accomplished by that user via the GUI.
Secure Access
Communication between the remote client and the WS Endpoint can be configured to be encrypted (Secure SSL).
Single Port Access
The remote services should not require multiple ports to be opened in the customer environment.
Client support
For remote Java clients we will supply artifacts to simplify and speed client development.
Non-Java client support through WSDL client generation.
Satisfy Initial Integration Goals
The initial set of offered services will be guided based on satisfying the currently selected Use Cases.
The proposed solution is to provide a Web Service remote API based on JBossWS 3.0.4/JAX-WS. This will provide the ability to communicate in a secured way over a single port, typically the standard RHQ port of 7080 (unsecure) or 7443 (secure).
For Java clients we plan to also provide a Serialization based remoting solution, lighter weight than a WSDL based client.
All remote sessions must begin by calling a login service which, given proper credentials, will return a Subject that must be provided on each subsequent remote service call. A logout service call will typically end the session. Multiple sessions may run concurrently using the same credentials.
The Use Cases provide the guidance for the original remote services and new remote services
The use cases give a more detailed idea of what the API must offer. Based on the existing use cases following lists summarize the current requirements:
Authenticated sessions
Authorized services
Export/Read-Only focus
Resource and Group Level services
Operational control (i.e. Operation execution)
Live/Current metric data
User management
Deployment
Most Administration
Content
HA
Template
Role
Group Definition/Creation
Dyna-Group Calculation
Configuration update
Inventory import/add/uninventory/delete
Applicable to all use cases:
login/logout will start/end all service interaction
resources includes resource groups where applicable
find a JBossAS resource of interest
start/stop/restart the JBossAS resource
find resource(s) of interest
get Alert History
find resources or plugins of interest
get the current configuration
Update the configuration
find resources of interest
get the current metric data
find resources of interest
get event history
The CLI should be able to leverage the remote API as a remote client. Use cases of the CLI are therefore also candidates for use cases of the remote API.
Priority: High
check user existence
add user
optionally, perform password mgmt
assign to existing roles
or
delete user
or update user
Source: M. Dickson
Support CLI-based or direct deployments of ear/war/jar/scripts
always want to import all jboss-as
always want to ignore certain other servers that may be running
come up with that forumla, then script it as each new box is added
also, be able to rename according to some internal conventions to make identification easier wrt infrastructure
need to expose connection properties as well as query for machine traits
sla reporting
figure out the percentage downtime across the enterprise / each box / each server
flexible alert notifications
today we don't implement "send me emails once / hr containing all alerts that have triggered"
integration with EmailManagerBean
system activity
query all BLAH created in the last X timeframe, groupby user (also support arbitrary timeframes)
BLAH := op defs / alert def / plugin configuration changes / visible groups created
dynagroup enhancements
dynagroups may not support expression to create groups properly (name contains substr1 or substr2)
so resource search and get the dynagroups grouping functionality via scripts
cron the script so as to mimic dynagroup recalculation intervals
ldap integration
new ldap users become new JON users and have roles/perms automatically setup for them
when user leaves ldap, then automatically disable corresponding JON account
how to provide ldap query funcs - ldap plugin, exposed slsb, tell them to use 3rd party api?
scheduled patch rollout
automatically add all resources in some group to a channel
patch a single instance or multiple instances
aggregate the statuses of "group patch" rollout
complex alert actions
execute operation (with arguments) on some arbitrary resource, as a result of an alert
pass some contextual information from the alert into the operation
can we make this simple for alerting on different levels - resource, group, template?
geographic affinity
query agents and group them into affinity based on location, name, subnet, etc
which agents are NOT connected to their primary?
might be indication of network health or unexpected failover events
also, are any agents not reporting back? last heard from time is greater than X
script chaining
instead of having to copy/paste functionality between scripts, allow decomposition
each script does some elemental work, can chain them together during a user session
login script, action script, logout script
dynamic favorites
add to / remove from resource / group / chart favorites based on rules
perhaps machines with ISSUES become favorites so they can easily be identified/worked on by ops
ISSUES := currently down, alerting often, problem metrics
reporting
recently added resources, anything imported in the last day - counts by resource category, resource type, agent, etc
system metrics / min - group by server, group by agent
report hardware summary for each machine, easy to see whether collection frequency is too high given physical limitations
hot-spot metric scheduling
if metric-based alert is triggered, automatically increase frequency of collection for that metric
after a restart, collect metrics quickly until box is proven stable, then decrease collection interval
alert escalation
instead of using notification policy, programmatically send alert email to some user
if "issue" not resolved in X time, send to next user in the list
question - is there a way to integrate this list into the core without too much work?
do escalation policies require us to implement alert ack'ing? (acknowledgements)
follow-the-sun alerting
similar to alert escalation, except that different users are notified depending on what time it is
if alert occurs at 18:00 UCT, notify the US support team, if 10:00 UTC notify the EU support team
maintenance windows
temporarily disable alerts across resource or group according to known maintenance windowsh2. Remote Clients
If time permits we will provide a client library for remote Java clients. This would include the Java Remote interfaces as well as the Java classes involved in the Remote methods. For non-Java clients the clients will need to be generated from the WSDL. Developer-level instructions for building remote clients will be provided.
The new Subsystem View Search queries may need to be exposed via Remote. Use cases may be added for this.
A JSON interface is a secondary goal but development resources will not be put on this effort if it endangers the WS delivery. It is hoped that JSON interfaces may be easily generated off the WS definitions.
How diligent should we be about minimizing the number of types exposed in client and therefore required for operation. Reducing the exposed types may reduce the power and flexibilty of the API but will simplify the clients and/or client generation.
parameters
Decision: Avoid exposing 3rd party types. Provide flexible signatures.
return types
Decision: Avoid exposing 3rd party types.
exceptions (perhaps a single Exception type, or just Exception, or no Throws clauses?)
Decision: Avoid exposing 3rd party types.
e.g. LookupUtil.getSubjectManagerRemote();
Decision: Do not integrate remotes into the current LookupUtil but may provide a separate LookupUtilRemote to support remote Java clients.
Decision: Provide Serialiation-based remoting for Java clients, based on ghinkle remoting solution, piggyback on 7080 port.
Simeon Pinder(Tasked with evaluating our existing efforts in Remoting, I wanted to capture the following thoughts as they applied to our external interface)
batch many commands to manipulate JON servers and the content they're managing.
read metric and/or alert information( or batches therof) for any one resource that JON is managing/monitoring.
use/integrate the management capabilities of JON or it's managed resources into a larger integrated offering.
the remoting audiences' needs can be largely served by exposing JON functionality or a subset of that same functionality over 'command line'(CLI) and XML/SOAP(Web Service) interfaces simultaneously. Successfully exposing these 'remoting' apis mean that integrating/administrative client requests can now come from any application and/or language that can put together valid XML or text requests.
From experience, the application interface exposed over CLI tends to be more human readable and broken down into simpler command sets displayed as pages of text. Users expect and are comfortable with short commands that automate some task.
No additional toolkits are usually available or required to contruct requests or operations. Command sets are kept small enough as to make such toolkits superfluous. Anything that is not easily achievable or consumable by the commands available should be obtained through the JON web UI or potentially through the XML remoting interface.
The exposed operations here tend to be more api oriented, focusing on machine readable methods to expose the underlying object model developed for an application before remoting was even considered. The side effect here is that successfully consuming these interfaces has historically been very challenging for non trivial applications. In other words, using the exposed SOAP interface for a given application can mean a WSDL with thousands of operations and thousands of lines of xsd(verbose type definition) with very little context as to which order to call operations in. It's analagous to a large java class with multiple operations and types where you're only given the method names(which you hope were done well) to guide you to the proper usage of the code. As developers we typically have an IDE and the ability to walk through and introspect each operation and implementation as the ultimate guide to understanding correct operation.
Formal documentation about which operations and correct ordering can help alleviate the above problem to some extent but suffers from the following problems:
traditional synch/stale issues where information is out of date with most implementation changes.
the delivered documentation for any one application interface is now necessaily a combination of WSDL and some formal documentation medium. While the WSDL is the formal machine readable interface for the exposed application, it is also one of the most confusing parts of consuming a remoting inferface for developers and lay consumers alike. Most people who speak WSDL forget how unintuitive that description/interface is to actually consume or even understand.
Due to WSDL consumption concerns just mentioned, the majority of consumers will leverage some toolkit to facilitate successful consumption. Unless the consumers are using a recent toolkit and annotation enhancements, the process is still quite painful. Modern languages like .Net and Java have already enhanced their languages to hide the implementaiton concerns/details of webservice consumption. It is important to note that the available webservice toolkits for integration/remoting for external consumers is heavily influenced by the current dependencies of the existing external application. In other words, if you're a java application it may be non-trivial to deploy an additional updated jdk to utilize webservice enhancements for interoperation. If you are a C or C++ based application you may be stuck with GSoap implentations that have not yet added annotation support or transparent proxying. An additional concern for webservice consumption is that while WSDL is the accepted standard for an XML api interface and that there is considerable tooling around WSDL consumption, much of that tooling is dated and may not have full support for all the generated XSD types and the accompanying WSDLs generated with updated tooling.
easiest consumption/integration path
* .Net:
Early to add functional Webservice annotations to their language, much of the type generation and automatic proxying exists as libraries and standard components. Only concerns may be actual integration and xsd type integration on actual implementations.
* Java(1.5 and greater)
Another easy one as the tooling and annotations do all creation, type definition and serialization/deserialization in a standard way with almost no added effort. Our greatest concern is to expose valid WSDLs which we do easily. This is the most trivial case and needs no further discussion.
Older Toolkits
WSDL consumption is sufficiently painful as to warrant concerns.
Type generation and connection of proxies is still fairly manual.
GSoap
Axis*
Web languages(PHP,etc...)
The key takeaway here is that up to now, most applications have simply defined their remoting/integration points by throwing up a WSDL and treating the consumption of that WSDL as a trivial process left up to the customer. Without modern tooling, consuming a 500K wsdl can be non-trivial as there is a lot of stitching that usually needs to occur to get successful connections to work. I've seen 1.5Mb and greater wsdls with several hundred operations for many different objects in the same interface.
( End of Scope/Detailed discussion )
Recommendation
After checking out the beans that we mean to expose(~ 10-15), the amount of operations is fairly small and continuing on this path to completion with the addition of the following documentation/tutorials showing:
Primer on the general objects that we expose(Accounts,Content,etc..ref existing docs.. as we should assume familiarity with those concepts already.)
How to initiate a successful connection
How to initiate conversation with the existing major beans for functionality(Schedules, Alerts, Events, etc.)
these integration/client steps with code snippets should make for a fairly functional webservice interface for most clients and tool kits.
We should keep in mind when expanding the amount of beans and methods, the discussions above, as JAX-WS makes remoting a lot simpler than it ever has been and still simpler than is available for many integrators. While integration code may be a few lines of code in java, for consumers using GSoap or Axis* the integrations can become annoying if the exposed information increases dramatically. As it stands I did a quick test(GSoap) but the Wsdls do compile down to types as expected with simple types. We should watch what happens when we build more complicated types like Configuration to monitor how consumable we continue to be with external SOAP toolkits...as JAX-WS on client and server is a trivial case.
(Recommended) Continue to flesh out existing MBeans defined:
For many applications there is a single WSDL interface for all of the exposed information. We've decomposed the problem a little but a small amount of documentation should be able to clarify that distinction.
Nice: Each SLSB maps to a WSDL. Focuses the business operations for a very specific object. One massive WSDL with all the types, operations, etc.. would be a little less consumble and a bit more expensive hit with each "Service" call from the java clients.
We might want to consider renaming the exposed Service names on the beans to:
-> SubjectManager --> UserAccountManager
Future Investigation tasks(shelved due to time frame)
Build WS-Management protocol handling into the jboss remoting options:
Status: Not enough time available to give this it's due analysis.
Pro: Pushes a Resource orient approach to each external interface. Like REST except leverages the WS* standards for serialization.
Con: Does not enjoy much industry adoption as a raw(WS*) webservice standards.
Pro: Should be able to build WSDL wrapper for WS-Man implementations so that existing WS* tooling continues to work.
Build QMF adapter and attach QMF servers?
Status: Not enough time available to give this it's due analysis. I suspect that this will necessitate the need for an additional server and port, but I'ave also heard of QMF adapters for JBoss that already exist.
Pros: Compresses payloads to binary format so should be faster throughput.
Cons: No real concept of meta data for automatic consumption. Basically without the concept of a WSDL, each client will require a person to parse/learn and custom build client server content for successful integration.
Con: No tooling around automatic metadata consumption.
Con: Lacks industry standard adoption of WS*.