A GBeanMBean is a J2EE Management Managed Object, and is standard base for Geronimo services. GBean is a class or object that Geronimo the container can manage the lifecycle of. So, for example, when you deploy parts into a container you want to start them and stop them, and they have dependencies: Such as 'Bean A' can only start up when 'Bean B' is ready to go because 'Bean B' provides services that 'Bean A' needs. So, GBeans are Geronimo's way of packaging up things are that need to be managed, and can express dependencies. The GBeans architecture lies at the heart of Geronimo's power to enable developers to move or work with their existing J2EE assets, whether Open Source or commercial.
GBeans are designed to let you take things you have, put a GBean wrapper around them, and use that to bridge the JSR 77 lifecycle requirements which GBeans support). You can take anything lying around and get it to work with GBeans. In addition, the GBeans will let developers bring other existing Open Source Java projects into the Geronimo orbit.
This wraps one or more target POJOs and exposes the attributes and operations according to a supplied GBeanInfo instance. The GBeanMBean also supports caching of attribute values and invocation results which can reduce the number of calls to a target.
- Gbeans are way of providing managements services to Geronimo
- It is implemented on top of the JMX right now but supposes to be independent of JMX. User should be able to use them without knowledge of the JMX. And it can be make independent of GBeans .
- The GBean can be converted into the MBean using the GBeanMBean and use the JMX to give the services
Grab the source code and search for the implementators of the GBeanLifecycle. It is a good way to find GBeans examples. It's been found that the jetty module and the GBeanTest class are quite helpful.
TODO: Add the fully qualified class names
How to write GBean
- A GBean may implement the optional org.apache.geronimo.gbean.GBeanLifecycle interface. When a GBean implements this interface, the implementation will get lifecycle callbacks.
- They can have attributes with getters and setters. There are attributes that are final and I think they are standard .. (What is the list of them) e.g. name, Kernel (they can use to get hold of the system info, have a look at the sample GBeans.) There are ordinary attributes .. have getters and setters
- GBeans can have methods ..
- A GBean's constructor MUST NOT call its own member functions which are declared in its GBeanInfo!!!
- A GBean MUST implement a method having the following signature:
This method provides meta-data about the attributes, operations and references exposed or used by the GBean. It is standard practice (a Geronimo pattern) to initialize this meta-data in a static block initializer. The following block depicts such an approach:
Attributes and references MUST be compliant wit the following naming conventions: attributes MUST start with a lower case first character; and references must should start with an upper case first character. This simple naming convention should simplify the configuration of a GBean.
Step 1: Your first simple GBean
Compile the class using the following command (TODO: create a maven task to compile a user's gbeans; simply find a better way).
TODO: Change what follows in this section (temporarily useful)
Create a jar with the gbean class and place it into <geronimo_home>/assembly/target/geronimo-1.0-SNAPSHOT/repository/example1.
How to deploy GBean
Deploying a GBean onto Geronimo requires to create a specialised Geronimo plan (aka configuration). It's similar to J2EE deployment descriptors as it also describes what it looks like and what references to other GBean it must have started before it starts up.
The plan has to conform to schema/geronimo-config.xsd (in the repo it's in modules/deployment/src/schema/geronimo-config.xsd)
Here is a part of the deployment descriptor for the gbeans already available in the binary distribution of Geronimo (it's modules/assembly/src/plan/j2ee-server-plan.xml in the repo). It looks really scary if this is your first time seeing one. Down below we have a simple one that we'll use for your GBean.
See also BROKEN INTERWIKI LINK to wiki:Deployment#head-5cbd584046863bc7b753e57e8681a98a87f36f0f (label = Service configuration and deployment).
TODO: Describe what these elements mean (here or even better in xsd)
So that was scary. The next section describes the deployment plan necessary for your GBean. It's really not so bad...
Step 2: Your first deployment plan
Here's the plan of your first simple GBean - MyGBean. The gbean doesn't expose any attributes or have references to other GBean.
There are two ways to deploy the GBean to your server, the so-called "offline" mode for when your server isn't running, and the "online" mode, when it is. Both are outlined below. Deploying the gbean requires to execute Geronimo Deployer. It boils down to executing an executable jar bin/deployer.jar.
When the Geronimo server isn't running, it's possible to add a GBean to it's configuration, and then start the GBean later when the server is running.
First, 'distribute' the GBean to the server :
This will do all the necessary things to get the GBean to the server, but the GBean won't be running when the server starts.
Now, start the server :
And when that is complete, start your GBean :
You'll be prompted for the username and password in order to start the GBean, as shown above. Use the values shown above.
Note that unless you start the server "in the background", you'll need another command prompt to start your GBean.
After starting, you should see the following in your server log :
When you already have a server running, you can distribute and start the GBean in one step :
And you'll see a slightly different message in the log.
How to run GBean
Step 3: Your first GBean in action
Once the deployment completes, start the following command from the Geronimo home directory:
You should see the following output on the console:
The line Loaded Configuration geronimo.config:name="MyGBean" indicates that your first GBean is really deployed and running! Hurray!
You may also want to see some information about the gbean in the Geronimo Debug Console. Start the server with the following command:
And here is how to run the gbean programatically:
Having created a GBean like this to start/stop/set values/invoke operations and GBean service use code like follows
Other questions to be answered later
If you feel you can answer some of the questions please do so!
What is GBean Meta Data?
What does the GBeanInfo class represent?
Can I configure my GBean using a flat file?
How do I manage the attributes of my GBean remotely?
GBeans are exposed as MBeans via the JMX kernel. Hence, it is possible to control/query them as we would have control Ã‚"standardÃ‚" MBeans.
For instance, to manage a given MBean remotely, it is possible to leverage the Java Management Extensions Remote API(JSR 160), which is supported by Geronimo.
More accurately, two services need to be up and running in order to enable the RMI Connector defined by JSR 160 on the server-side:
- org.apache.geronimo.system.RMIRegistryService: starts a RMI registry on the specified port. This service is part of the "system" plan, in other words it is always started; and
- org.apache.geronimo.jmxremoting.JMXConnector: it creates a RMI Connector server and exports it to the RMI registry embedded in its URL (see JSR 160 for more details about the format of the URL). You can have a look to the j2ee-server plan for more details on its GBean definition.
If the two above services are running, then the following snippet will get you an MBeanServerConnection:
Note: username and password must be defined by the org.apache.geronimo.security.jaas.ConfigurationEntry having the name defined by the applicationConfigName attribute of the org.apache.geronimo.jmxremoting.JMXConnector service.
Having said that, if you do not want to write code, you can also use a JMX console supporting JSR 160.
How do I call methods on a GBean deployed in the server from a J2EE App?
First get a handle to the kernel by calling KernelRegistry.getSingleKernel() and then use the invoke methods in the Kernel interface. eg:
where hello() is a method on the GBean. This will work provided that the GBean is running in the same server instance where the J2EE application is deployed.