geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Geronimo Wiki] Update of "Geronimo Management API" by AaronMulder
Date Sun, 17 Jul 2005 15:24:58 GMT
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.
  

Mime
View raw message