Introducing: EASC

at 2005-09-28 in Examples by friebe (0 comments)

During the last couple of months we have developed an API that lets you connect PHP to Java enterprise application servers. Though it is still in an experimental status I'd like to give you a quick overview of what this API is (and what it is not):

All client-side code is written in userland PHP
This API does not require any external libraries except those built in to PHP
Requires our JMX MBean to be deployed in your application server
At the moment, only JBoss is supported since we do not have access to other app servers. Also, the server must run under JDK 1.5 (aka Java 5).
The functionality is not restricted to PHP and the XP framework
If someone were to write a Perl or Python implementation, it should work too.
The XP framework's implementation mimics Java RMI
Except for small differences (partially language-based) it pretty much also works the same. See below for more details.

Continue reading to learn more about our Entreprise Application Server Connectivity API.

The basic functionality is best illustrated together with a picture:

EASC overview diagram

It's basically quite simple: The client (here: A PHP script) uses the XP client side API to look up and retrieve objects from the naming directory and to then execute so-called remote methods on them. These calls are marshalled and sent over the network to the EASC MBean, which in turn unmarshals them, locates the EJB and executes the methods on them, returning results (or exceptions).

Let's say we already have a JBoss application server running (getting that to run is another - long - story

). First of all, you'll need the EASC MBean deployed in it (you can skip this section if you already have but that's quite unrealistic except maybe if you're working at Schlund+Partner).

Make sure you have JDK 1.5+ and Apache Ant installed:
$ ant -version Apache Ant version 1.6.2 compiled on July 16 2004 $ java -version java version "1.5.0-p1" [...]
Make sure no service is listening on port 6448 of the machine your JBoss is running (edit resources/jboss-service.xml and the following examples in case it is or shut down that service).
In your XP svn checkout, cd to experiments/arena/easc/java
Type ant test. You should see some output scrolling by and then finally OK (63 tests).
Create a JBoss Service Application Archive by typing ant jboss-sar. You'll find a file called xp-easc-1.0.sar in the dist/ directory after the ant task has finished.
Deploy it! You can check if it worked by looking at your JBoss logfile. It will contain the line Started net.xp_framework.easc:service=EascService (unless, of course, you've disabled logging...)

Now that you've made your JBoss understand PHP, you can basically start right away with programming

, unless of course you don't know where to start. We've got a solution for your problems - along with the EASC API, we provide a set of simple test beans (at the time writing, exactly one). To get them deployed, follow these steps:

In your XP svn checkout, cd to experiments/arena/easc/beans
Type ant ejb-jar. This will create a file called beans.jar in the dist/ subdirectory
Deploy it! The JBoss logfile will read Deployed: file:/home/java/jboss-4.0.2/server/real/deploy/beans.jar or something similar in case of success

Note: We use (and bundle, so no need for any installation here) XDoclet to generate the interfaces and the ejb-jar.xml file.

That's it for prerequisites. Let's get back to good-old PHP

Accessing the CalculatorBean's methods from within PHP is similar to the way it's done in Java:

Use the entry point class (Java: InitialContext, XP: Remote)
Perform a naming lookup to retrieve the EJB's home interface (Note: In EJB 3.x, home interfaces will vanish and you'll lookup the beans directly)
Create an instance by invoking create() on the home interface
Invoke methods on the retrieved instance as if they were regular methods

Example:

  require('lang.base.php');
  uses('Remote', 'util.cmd.Console');

  try(); {
    $remote= &Remote::forName('xp://jboss.example.com:6448/');
    $home= &$remote->lookup('xp/demo/Calculator');
  } if (catch('RemoteException', $e)) {
    $e->printStackTrace();
    exit();
  }

  with ($calculator= &$home->create()); {
    Console::writeLine('1 + 2 = ', $calculator->add(1, 2));
  }

To see the PHP client side in action, follow these steps:

In your XP svn checkout, cd to experiments/arena/easc/clients
Type php calculator.php to read the usage
Type php calculator.php hostname-of-your.jboss. You'll see some (fairly basic) calculations being made and their results printed onscreen.

That's it: You've invoked methods on a Java Enterprise Bean from PHP!

If you inspect the clients directory, you will see that the client side not only consists of the calculator.php script but also of three other files:

net/xp_framework/beans/stateless/CalculatorHome.class.php
Contains the CalculatorHome interface
net/xp_framework/beans/stateless/Calculator.class.php
Contains the Calculator interface
net/xp_framework/beans/common/Complex.class.php
Contains the Complex class

These files are needed just as you need the ...RemoteHome and ...Remote interfaces and all used value objects in Java if you're writing a client. At the moment, they're still hand-written; autogenerating them will be possible in the future (think WSDL...).

What's left to say is that there are still many missing parts (e.g. using beans that require client authentication, JMS, HA-JNDI...) and some that haven't been tested yet (transactions) as well as missing integration tests (that's why all of the API resides in the experiments directory). Because we have real-world use cases coming up at Schlund+Partner though, we'll continue working on this. We're "releasing" it at this early stage nevertheless to be able to gather feedback.

You can subscribe to the XP framework's news by using RSS syndication.

Introducing: EASC

Subscribe

Categories

Related