Dear Wiki user, You have subscribed to a wiki page or wiki category on "Geronimo Wiki" for change notification. The following page has been changed by AaronMulder: http://wiki.apache.org/geronimo/Geronimo_Management_API ------------------------------------------------------------------------------ new Class[]{arg_types}, new String[]{args}); }}} - It's pretty hard to code to an API like that. If you're determined to write a portable JSR-77 management tool, then you need to learn JSR-77 by heart, and too bad. But otherwise, how can you know what object names to use, what method names to use, what methods take what argument types, what attributes are available, what to cast the results to, and so on? Well, you can look it up, but can you imagine writing more fragile code? Code completion doesn't help, the compiler and IDE can't catch your problems, etc. If you're not familiar with the API, there's nothing to do but read documentation or browse code. + It's pretty hard to code to an API like that. If you're determined to write a portable JSR-77 management tool, then you need to learn JSR-77 by heart, and too bad. But otherwise, how can you know what object names to use, what method names to use, what methods take what argument types, what attributes are available, what to cast the results to, and so on? Well, you can look it up, but can you imagine writing more fragile code? Code completion doesn't help, the compiler and IDE can't catch your problems, etc. If you're not familiar with the API, there's nothing to do but read documentation or browse code. But Geronimo has a ''ton'' of code, and if you're given an arbitrary !ObjectName, there's no way to figure out where in all that code is the class that you should cast this sucker to. + To try to clarify my concerns: + + * Avoid requiring passing cryptic parameters to the API (object name, method name, argument Class types, etc.) + * Avoid casting what you get back from the API (return types of Object, Set, etc.) + * Avoid needing to know what to cast it ''to'' + * Make it easy to navigate from X to Child-of-X (especially not "get names-of-children, make cryptic call to get instances-of-children as Objects, then figure out what child types should be and cast to real child types") + * Related: Make it easy to learn the API by making it immediately obvious "if I have a Foo, what child objects does Foo have, and what types do ''they'' have?" + == So what's the solution? == I'm imagining an API like this: @@ -87, +95 @@ So this would be a mix of JSR-77 and not JSR-77. - On the JSR-77 side, it would include interfaces representing the JSR-77 components, and trying to keep to similar names and similarly named properties. The types would change -- for example, a JSR-77 J2EEDomain.getServers() method would return a list of ObjectNames for servers, and in this API it would instead return a list of J2EEServer objects. But the idea is that someone familiar with JSR-77 programming would find it easy to get up to speed. + On the JSR-77 side, it would include interfaces representing the JSR-77 components, and trying to keep to similar names and similarly named properties. The types would change -- for example, a JSR-77 J2EEDomain.getServers() method would return a list of !ObjectNames for servers, and in this API it would instead return a list of J2EEServer objects. But the idea is that someone familiar with JSR-77 programming would find it easy to get up to speed. - However, the API would also include non-JSR-77 components. For example, there's no "WebContainer" object in JSR-77, that would let you inspect and alter the listen port of Tomcat/Jetty, or configure the number of threads used, or which compiler is used for JSPs, and so on. The reason I want to extend beyond JSR-77 is that I want to give direct API access to all the things that something like the web console would need to do its job. + However, the API would also include non-JSR-77 components. For example, there's no "!WebContainer" object in JSR-77, that would let you inspect and alter the listen port of Tomcat/Jetty, or configure the number of threads used, or which compiler is used for JSPs, and so on. The reason I want to extend beyond JSR-77 is that I want to give direct API access to all the things that something like the web console would need to do its job. If we don't actually want the API to include references to other objects in the API, then we can have some kind of master to bootstrap the process and manage relationships. Something like: + {{{ + public interface Manager { + // root properties + J2EEDomain[] getDomains(); + + // domain properties + J2EEServer[] getServers(J2EEDomain domain); + SecurityRealm[] getSecurityRealms(J2EEDomain domain); + + // server properties + J2EEDeployedObject[] getDeployedObjects(J2EEServer server); + J2EEApplication[] getApplications(J2EEServer server); + J2EEAppClientModule[] getAppClients(J2EEServer server); + WebModule[] getWebModules(J2EEServer server); + EJBModule[] getEJBModules(J2EEServer server); + ResourceAdapterModule[] getRAModules(J2EEServer server); + J2EEResource[] getResources(J2EEServer server); + JCAResource[] getJCAResources(J2EEServer server); + JDBCResource[] getJDBCResources(J2EEServer server); + JMSResource[] getJMSResources(J2EEServer server); + JVM[] getJavaVMs(J2EEServer server); + + //application properties, resource properties, etc. + ... + }}} + + or perhaps + {{{ public interface Manager { // root properties @@ -118, +154 @@ ... }}} + - This would give you an entry into the domain and related objects, and also let you navigate between objects without needing to manually do things based on the ObjectNames that all the JSR-77 classes return when you ask about their children. + This would give you an entry into the domain and related objects, and also let you navigate between objects without needing to manually do things based on the !ObjectNames that all the JSR-77 classes return when you ask about their children. == How could this be implemented? == We have GBeans that expose all the necessary properties and functions already. The only issue is providing an implementation of this API that accesses them. In many cases, we might supply interfaces that the GBeans could implement. Still, here might be some glue code between the interfaces defined above and the actual GBeans. - The interfaces themselves probably wouldn't be as extensive as the GBeans. For example, the WebContainer interface would likely have the least-common-denominator configuration options across Jetty and Tomcat (and maybe even less than that). Still, a programmer always has access to the raw GBeans to go deeper than the common API allows. But this way you can use normal OO code for the bulk of your management tasks, and only go to the paradigm that started this page if you really need to. + The interfaces themselves probably wouldn't be as extensive as the GBeans. For example, the !WebContainer interface would likely have the least-common-denominator configuration options across Jetty and Tomcat (and maybe even less than that). Still, a programmer always has access to the raw GBeans to go deeper than the common API allows. But this way you can use normal OO code for the bulk of your management tasks, and only go to the paradigm that started this page if you really need to. Note that it is not my intention to start a "build the world" project to provide a totally comprehensive management API for Geronimo. Instead, I'd plan to start small, and grow it as tools such as the web console expand into new areas. "On demand" development of the management API, I guess. @@ -138, +175 @@ == What's the advantage? Is it worth the trouble? == - Well, back to the example at the top of the page. I'd much rather see it like this (where JDBCDataSource is an interface in the management API, based on the JDBCDataSource definition in JSR-77): + Well, back to the example at the top of the page. I'd much rather see it like this (where JDBC!DataSource is an interface in the management API, based on the JDBC!DataSource definition in JSR-77): {{{ JDBCDataSource ds = ...; DataSourceInfo info = new DataSourceInfo(); @@ -156, +193 @@ In fact, maybe the tool could just dispense with the `DataSourceInfo` altogether and just use `JDBCDataSource` as its object model, depending on whether the `DataSourceInfo` class has any UI-specific stuff in it. - In any case, note that there are no Strings in the code above. It's all verified by the compiler, you can inspect an unfamiliar interface via code completion and popup JavaDoc, etc. + In any case, note that there are no Strings in the code above. It's all verified by the compiler, you can inspect an unfamiliar interface via code completion and popup !JavaDoc, etc. I think something like this would make it much easier to develop management tools such as the web console. By using this API the tools would end up being specific to Geronimo, but that's OK for our purposes -- we're trying to make Geronimo more usable not write a console that can manage any J2EE server. And if we're going to be reusing code across tools, I would much rather it be an API layer like this, not copying and pasting kernel invocations with string arguments and so on. @@ -164, +201 @@ Please confirm that the API: - * is a set of EXTERNAL wrapper APIs for management ONLY when Geronimo assumes the "J2EE personality" + * is a set of EXTERNAL wrapper APIs for management ONLY when Geronimo assumes the "J2EE personality" + * '''Ans:''' yes, though WRT "external" it may end up with some helper GBeans deployed in Geronimo. The web console requires this, and I haven't yet looked to see whether it can be avoided. * provides programmer friendly semantics to access the guts of Geronimo, for management/monitoring/tuning(?) purposes ONLY (enforced by available operations) + * '''Ans:''' yes * a subset of this API provides portable JSR-77 access to Geronimo, for the benefits of other JSR-77 compliant tools + * '''Ans:''' no -- strict JSR-77 does not use ''any'' API other than the Management EJB. We will have JSR-77 "lookalike" functions. That is, if JSR-77 requires that you have a JVM object with a "vendor" property, we will have a JVM interface with a getVendor method. However, to remain portable, JSR-77 code would still need to access it using MEJB.getAttribute("jvm_object_name", "vendor") and not by calling our methods. There's nothing we can do to make life easier on portable JSR-77 developers -- I'm just hoping that our easy-to-use alternative won't look alien if you happen to be familiar with JSR-77. Suggestion... create this layer in a reusable(extensible?) manner, to enable the creation of other G-management APIs applicable when Geronimo assumes other "personalities" (J2EE subset, J2EE superset, no J2EE - purely embedded, etc) + * '''Ans:''' perhaps, though I'm not clear on how to make this that flexible yet still achieve all the other goals. For now, I'd like to solve the first problem first and consider refactoring to solve additional problems later.