Overview

OSB installation in a development environment consists of a completely separate Weblogic instance and yet another ‘special installation’ of Eclipse. You can’t use existing Eclipse installations. Nor is it recommend to use one of the five other existing Weblogic instances that Oracle products thoughtfully demand their own copy thereof (SOA Suite, I am looking at you).

Installation process

This is the procedure for installing OSB development environment.

As network firewall policy prevents the downloading of files, you will need to use installation media located within <companyname> network. Take the files conveniently stored on network server <location redacted> and copy them into a directory on your local computer. This directory is hereafter referred to as ‘installation files directory’ below.

Install Weblogic

1. Go to the installation files directory.
2. Run the executable file wls1033_oepe111150_win32.exe
3. This action launches the Oracle Installer for the Weblogic instance. It takes some time to run so contemplate the meaning of your life for a few minutes while it does. Maybe get a cup of tea. Stretch your legs. Think about lunch or your next holiday. File a support request for more memory. You should get at least 8GB.
4. Okay that’s it, you’ll finally see the Oracle Weblogic 10.3.3.0 installer. Think about the fact that Oracle sees fit to put “instructions” on the first screen telling you what the “Next” button does. This is advanced JEE server technology you’re installing, and potentially, Oracle think you don’t know what the “Next” button does. Maybe this reflects the level of experience inside Oracle, or perhaps it is indicative of the depth of respect in which Oracle holds their customers.
5. Press the “Next” button. The next screen you will see  is very important. If you fsck it up you’ll have to uninstall and start over. It does not have any instructions, but that’s OK, we’ve done it here in this wiki page for you. Pay attention.
6. DO. NOT. ACCEPT. THE. DEFAULT. Especially if you installed SOA Suite or some other Oracle product before you installed this one. Double especially if you still want that product to work.
7. SELECT “Create a new Middleware Home” (THIS IS VERY IMPORTANT)
8. TYPE a name of an Appropriate Directory. I used “C:\Oracle\OSB_Middleware”
9. PRESS The “Next” button. Use the “Back” button if you need to see the instructions about how to use the “Next” button that Oracle conveniently provided for you on the first Screen. No, don’t do that. If you do that you’ll probably have to do this proceedure again and it will just make this entire experience last longer than it needs to. This is not a recommended practice.
10. The next screen demands that you give Oracle your Email Address to get “security updates”. It also wants a thing called your “My Oracle Support Password” (I suspect this is what might have been known as Oracle TechNet). As we both know, the best possible security measure is not to give out your password to strange programs that demand it.
11. As I planned on giving them my <workcompany> email, and as my Technet sub doesn’t use that Email address, I also unchecked the “I wish to receive security updated via My Oracle Support” check box.
12. Are you Sure? YES I’M VERY SURE. I would like to be “ignorant of security updates” and also Oracle spam. Ignorance is Bliss.
13. Look at that, I can’t give them my email address after all, what they really meant was “type your Oracle Support user id”. Press “Next”.
14. Now you have to choose whether you want a “Typical” installation or a “Custom” one. I chose “Typical”, which, being an Oracle installation, I expect to require an 8-core 64GB RAM 2TB SAN SSD -based supercomputer with a external 4-way Oracle RAC for configuration (“infrastructure”) DB in order to have enough grunt to service about 3 requests a minute. Press “Next”.
15. There’s a lot of choices here about the various subdirectories under the Middleware Home Directory that you created further back. I recommend accepting the defaults, but you can probably cause yourself countless of fun trolling on the My Oracle Support forums as you get ever-more-desparate for a solution to a very obscure problem that the phone support have no idea about and that was likely caused by you mucking about these defaults, causing the support personel to simply recommend you to reinstall the product, if you really feel the need to change them here.
16. If you can remember the instruction about the use of the “Next” button at step 4, then Press “Next”.
17. Now you can choose whether you want to put the shortcuts for “All users” or just you (“Local user”). If you are the BOFH I recommend “All Users”. As this is the default, we can all safely assume that the BOFH works for Oracle and is now responsible for designing their installation processes. Accept the default, and press “Next”.
18. The next screen is a summary of what you’ll be installing. You can also select each item and see a summary of what it does. Ponder the mystery of Oracle, and press “Next”.
19. Keep pondering that mystery while Oracle Weblogic Server 11g Release 1 (10.3.3.0) is installed. It takes a little bit of time. While it does that, you might to book that Holiday, get another cup of tea, or chase up that support request for the additional RAM you’ll be soon needing.
20. Congratulations! Installation is complete.
21. I opted to leave the “Run Quickstart” option checked.
22. Press “Done”. There are no onscreen instructions for this button.
23. Quickstart will run. It’s just a link farm.

Install Oracle Enterprise Pack for Eclipse (OEPE aka “Special Eclipse”)

1. Go to the installation files directory
2. Extract the file oepe-galileo-all-in-one-11.1.1.5.0.201003170852-win32.zip … I used 7zip and made sure to put it into a subdirectory of the installation files directory.
3. It’s kind of pretty big, takes a cople of minutes.
4. Just like a regular version of Eclipse, once this is unzipped, it’s installed. However it’s not a regular version of Eclipse. It is a “special” Eclipse that went to “special” school.
5. Although this directory can probably live anywhere, it’s a good idea to copy this directory into the new Oracle Middleware Home that you created when you installed Weblogic. Look I really have no idea why this is the case, however, it’s not good to anger the Oracle by using you regular development directories. ORACLE_HOME sweet ORACLE_HOME it is then.

Install OSB and OSB Dev Tools

1. Go to the installation files directory.
2. Extract the file ofm_osb_generic_11.1.1.3.0_disk1_1of1.zip … again I used 7zip and made sure to put it into a directory underneath the installation files directory.
3. Enter this directory. Enter the directory “osb” that will be created underneath it. Note that even though the file said “disk1_1of1″ in the file name that underneath here there’s two directories, Disk1 and Disk2.
4. Go into the directory “Disk1″
5. Run the executable file “setup.exe”
6. A DOS window opens which asks you for the location of a JRE in order to use Oracle Universal Installer. Probably. Exactly why the Weblogic installer didn’t need to know where the JDK was, I do not know. Probably it used a sensible installer rather then the Oracle Universal Installer. I don’t ever think I’ve ever seen an machine with two Oracle installations on it that didn’t also have two or more installations of the Oracle Universal Installer also installed on it. Its name perhaps means that it installs itself universally, rather than it is a product which has a universal use for installing other software. Ponder the mystery of the Oracle.
7. A JRE will be located in the original Oracle Middleware Home that you created when you installed Weblogic. In fact there’s at least two (Sun JDK and JRockit). Use the Sun JDK. For example, my value for the JDK was “C:\Oracle\OSB_Middleware\jdk160_18″. Press Enter.
8. Now the Universal Installer will actually attempt to install something. It says “You are about to install the Oracle Service Bus (OSB) and may install the Oracle Service Bus IDE and Oracle Service Bus Examples (OSBE). Before proceeding, make sure that you have installed and configured Oracle WebLogic Server 11g. If you want to design OSB applications in Eclipse, make sure Oracle Enterprise Package for Eclipse (OEPE) is installed.” Which is all true if you’ve been following this guide.
9. Press “Next”. There’s no instructions in this program for the use of the “Next” button. Someone ought to file a change request for that.
10. Now you can choose whether you want a “Typical” installation or a “Custom” one. Typically, choose “Typical”.
11. Press “Next”. I tried looking for online help here about the use of the “Next” button but I did not find anything.
12. It does a prerequisite check. It should pass, and if it doesn’t, you are probably screwed. If it does, you will be able to Press “Next”
13. At this next screen DO NOT ACCEPT THE DEFAULTS.
14. Choose the Oracle Middleware Home that you installed the Weblogic into at the first part of this installation procedure. E.g. I chose “C:\Oracle\OSB_Middleware”.
15. Once you do the previous step, ff you followed the instructions for the Special Eclipse (OEPE), it will have found it automatically. If not, choose the location where you installed the Special Eclipse (OEPE Location). For example, my value was “C:\Oracle\OSB_Middleware\oepe-galileo-all-in-one-11.1.1.5.0.201003170852-win32″
16. Press “Next”. Did you know that the Oracle at Delphi was a priestess called the ‘Pythoness’ who answered your question using gibberish verse. A Male Attendant of the Pythoness interpreted her raving mad gibberings and told you what they meant. For a fee. Does this sound familiar?
17. Review the installation details. When you are sure they are correct, press “Install”.
18. OSB will now install. It takes a little time so run those errands, go to lunch, get a coffee, dream of the Holiday you just Booked. I’d tell you to install the new 8GB of memory that you ordered before which surely has arrived by now, but that would mean turning your computer off. Best to wait until it’s finished then.

Recently I was learning ANTLR, trying to decide whether this was a right technology to pursue a particular project which involved parsing a preexisting message format. After a week of a spike, we decided that it was worth pursuing and started on earnest on the grammar for our project. However a week into this process, I had an epiphany … I was doing some things wrong with the ANTLR grammar which were now slowing progress in adding the new characteristics it needed to be complete. Many developers know this feeling; the features of my grammar that I had built over the first week were naive and now hampering it from expanding into the new requirements. I took it on myself to kill the entire grammar and start again. It took less than a day and half to replicate that week’s worth of work (i.e. pass the test suite which had built up around it).  I’ve done this before; scrap the first attempt at building a domain and try again. Here my domain was the same (it was after all defined in both a standards specification and in the many hundreds of thousands of sample messages we captured from an existing system), but its implementation needed refinement.

So I think that the rule about throwing away spikes can in fact be made a general axiom of programming:

When you are learning a new technology, make sure you throw away the first thing you build that works – to avoid accumulating your mistakes.

Thanks to Robert for the important qualifier “that works”.

N.B. my views about system rewrites have not changed regardless.

There is a web service inside a component, let’s call that component a ‘Node’, that receives something like (but not identical to!) an Event on its interface. Inside the Event is some data that the Node does not particularly care about (and actually has no access to – it’s just a byte[] as far as the Node can tell). However, the Node contains a Registry which enables components, lets call them Event Handlers, to register themselves with the Node, as available to process certain Events (i.e. decode that byte[] and do something with it) according to criteria which the EventHandler injects into the Node’s Registry.  EventHandler is an interface with a handful of simple methods related to handling the Event, and also registration with the Registry.

So, the process flow looks something like this: The Node first records the reception of the Event at the interface in a log. Then it tells the Registry about the Event, and the Registry produces the EventHandler(s) it needs to use.  The Registry gives the Node back the instances of the EventHandler interface. The Node then hands off the Event to the EventHandler, which does whatever it does unbeknownst to the Node, and returns a fairly simple EventResponse object. The Node records the EventResponse object in its log (i.e. a database) and returns it as the response to the web service call.

Consider the Node service method as looking something like this (you’ll have to excuse the Java 1.4-ness of this code, the WordPress code highlighting plugin apparently hates Java 5) :

  public List receive(Event event) {
    List responses = new ArrayList();
    for (EventHandler handler : this.registry.lookup(event.getMetadata())) {
      Response response = handler.handle(event);
      saveResponse(response, event, handler);
      responses.add(response);
    }
    return responses;
  }

To enable the wiring, the Registry has a method:

  void register(EventMetadata metadata, EventHandler handler)

and among other methods the EventHandler interface defines:

  void setRegistry(Registry registry)

Currently the WAR file imports the Node.JAR and a group of EventHandler.JAR files which are specific implementations for handling different kinds of Events. We configure it in Spring currently so that the specific EventHandler is injected with the Registry object (from the Node.JAR). The EventHandler implementation then registers itself with the Registry in a call-back operation, telling it what sort of Events it will handle.

This all works just fine at the moment. The problem with what we have is that it is all currently statically compiled into the WAR file.The WAR file specifies a Spring application context XML file which in turn loads the Spring configuration for the Node and Registry component, and every Spring application context for each Handler JAR included inside the WAR file’s WEB-INF/lib directory.

Now, we now don’t want every deployed instance of every Node to handle every possible Event. Currently we’ve got a small .properties file that actually tells another Spring component which EventHandlers are be to be instantiated or not. This is working fine when we only desire some Nodes to handle maybe one or two of a larger group of related Events. That is, where we currently don’t mind that the WAR file is identical in every respect on every Node — it’s just that each node contains a .properties file in its classpath that tells it which EventHandlers it is allowed to load and use (and therefore what Events it is capable of receiving, bearing in mind that when I say ‘Events’ there is really only one concrete type of Event, I mean the encrypted data which is held within the Event which is actually consumed by the Handler).

However, we are now in a situation where we want to use this same architecture for a completely different group of Events. We definitely don’t want to have to compile and assemble a new WAR file for different Nodes based on the Event cluster. We want to deploy a standardized Node.WAR which has available on its classpath a dynamic set of XxxEventHandler.JAR which can dynamically register themselves with the Node’s registry. There may be also a requirement for some related custom extension points in the future.

Initially we considered OSGi as the technology to enable this. After some discussion yesterday with people who know better about OSGi, this approach was rejected as impractical for the moment. Therefore last night I set out tooling about with the Spring 2.5.6 ApplicationContext and its related objects to see what could be done to enable dynamically-loaded JAR files within a parent Spring application context. Here is what I’ve discovered we can do, with only some small restrictions on developers writing the individual EventHandler implementations.

The first issue is, we need to locate a set of Spring application context XML file which should be on the classpath but not yet instantiated into any live Spring context.

Assuming we’re in a bean that’s ContextAware or otherwise has access to the Spring application context which is loading it, after the parent context has loaded and initialized (there are method hooks for this sort of thing) we can use the org.springframework.core.io.support.PathMatchingResourcePatternResolver class to search the classpath for a resource:

  PathMatchingResourcePatternResolver pmrl = new PathMatchingResourcePatternResolver(context.getClassLoader());
  Resource[] resources = pmrl.getResources(
    "classpath*:/net/crazymcphee/dynamiccontext/*/Crazy*DynamicContext.xml"
  );

Looking at the Spring 2.5.6 source code we found that the String passed to the getResources() method isn’t a proper regular expression, which is a pity. So you can’t do something like look for **/Crazy*DynamicContext.xml and expect to match a file Crazy*DynamicContext.xml in any package. Also we found that it had to prefixed with that classpath*: … yes, the asterix, literally … else it wouldn’t search the classpath, as opposed to the file path. So we’re restricted in the above example to a file called Crazy<something>DynamicContext.xml in a package exactly one deep from net.crazymcphee.dynamiccontext … e.g. net.crazymcphee.dynamiccontext.package.CrazyMcpheeDynamicPackage.xml matches but net.crazymcphee.dynamiccontext.package.sub.CrazySubDynamicPackage.xml and net.crazymcphee.dynamiccontext.CrazySuperDynamicPackage.xml do not. Therefore we will have a restriction on what package the dynamic context can be in and what it’s name will be. I don’t think that’s too onerous on our developers – we just have to pick a sensible standard.

The next part of the problem is that we have to load the ‘Resource’ thus found into a Spring context. This is pretty easy:

 for (Resource r : resources) {
   GenericApplicationContext createdContext = new GenericApplicationContext(context);
   XmlBeanDefinitionReader reader = new XmlBeanDefinitionReader(createdContext);
   int i = reader.loadBeanDefinitions(r);
 }

The int i will be set to the number of beans found in the createdContext. The createdContext will have the original context as its parent context, so it can gain access to any beans defined there (and also, although we are yet to test this (!), it should also be intercepted by the AOP-based transaction interceptors in the parent, and so forth).

The only other part of the puzzle may be to query the createdContext to see if it has any target beans within it, luckily for us an ApplicationContext has a method getBeansOfType(Class clazz) which will load all the beans of a particular type:

  for (Resource r : resources) {
    GenericApplicationContext createdContext = new GenericApplicationContext(context);
    XmlBeanDefinitionReader reader = new XmlBeanDefinitionReader(createdContext);
    int i = reader.loadBeanDefinitions(r);
    Map map = createdContext.getBeansOfType(EventHandler.class);
    for (Object o : map.keySet()) {
      EventHandler handler = (EventHandler) createdContext.getBean((String) o);
      // do some programmatic manipulation with the EventHandler that we found here
    }
  }

Using these three Spring features will enable us to be able to place a JAR file containing an interface implementation, and a Spring context XML file matching a particular pattern, into the classpath of our WAR, and on restart, we can dynamically pick up the newly inserted features into our application installation. I’ll report back when we get an actual production prototype together that can do this. Hopefully it will be OK to put the code in the blog too (if we make it generic enough).

If you have any further ideas or refinements to this idea, please leave them in the comments!

I don’t hold that software makes an existing business process “efficient” at all. Rather I think software makes possible a new process, which should be more “efficient” in terms of money gained less dollars spent – but its a new process, not the old one. In effect, new software creates new business opportunities. New software will only make an existing, unchanged process, less efficient, if a new business process is not designed along with the new software. If the business just wants new software without changing “what they do” they are wasting their money, IMHO.

Of course there is the possibility (probability?) the business doesn’t actually understand what it is they actually do anyway. This is not an uncommon position for many businesses that are happy to cruise along in neutral making some marginal profit on some marginal activity. Usually these businesses are also found to be beating their workers with sticks (usually only metaphorical ones unless they ‘offshore’ their operation to countries where killing your workers is just a part of ‘Business as Usual’. Typically they hold that marginal process can be made ‘better’ simply with just more exhortation (or threats) to greater and greater efforts at a totally demoralized (if not actively hostile) workforce, but I suspect that’s a story for another day!

The problem for Glassfish, as the second sentence of this ServerSide article states (see it straight from Oracle’s mouth here, and see also here) is that Oracle view it as being used for “non-mission critical department apps”. Glassfish’s superior technology (or otherwise) just doesn’t come into it. It’s not a factor (as it rarely every is).

Not so long ago Oracle spent a big wad of money acquiring an app server (Weblogic) and then a stack of more money porting all its other products into it and branding the resulting mess platform “Oracle Fusion Middleware 11g”. Now not only do they have their third app server (OC4J/OAS, Weblogic and Glassfish), but the Sun product suite includes products that compete with various Fusion Middleware 11g products (portals, ESBs, and so on). So on one hand you’ve got a “departmental” application server, which you can either licence for free by downloading the open-source version, or buy support for the fancier ‘Enterprise’ version, and on the other, an expensive, full-stack-integrated (all the way to the IDE), fully-branded strategic platform that Oracle just invested a vast amount of money into, and have been pushing like crazy onto customers the past six months. And it is the same sales team that will sell both this licensed “departmental” Glassfish. Therefore if you say the magic words like “need a cluster” or maybe “we might build a portal”, or “we are considering adopting a service-orientated architecture”, lo and behold you’ll find the molto-dinero “Fusion Middleware” based solution installed all over your sorry arse quicker than you can say “can you please explain this per-core with special CPU-architecture-loading-factor licencing schema to me once again and why is it a different price if I upgrade my hardware without adding any additional cores???“.

Let’s dissect those “key points” of Oracle’s strategy announcement:

Key Point	What they meant to say
GlassFish continues as the Java EE reference implementation and as an open source project.	We see it as the way to dominate the direction of Java EE for at least two years, but for Larry’s sake don’t try to use it in production.
Oracle’s strategic application server, Oracle WebLogic Server, together with GlassFish, provide world class Java EE infrastructure.	Oracle’s strategic application server, Oracle WebLogic Server something something something provide world-class something something infrastructure.
GlassFish Enterprise Server and WebLogic Server expected to share core components.	We are the Borg. Resistance is futile. You will be assimilated.
Oracle plans to add GlassFish Enterprise Server all WebLogic offerings.	Hey, look at this cute free “reference implementation” thingy that comes free with Weblogic! You could use that to run your departmental Wiki instead of having to pay us another fortune for more Weblogic licences. Did you say “WIKI”? Did we tell you all about the great wiki-like Enterprise 2.0 features available in the Oracle Fusion Middleware 11g offering? How many test environments did you say you needed licences for?
GlassFish Web Stack maintained for existing customers.	Not available for sale.
GlassFish Message Queue remains as the GlassFish messaging infrastructure.	We’re not expecting to sell any licences of this. Just use Oracle Fusion Middleware’s SOA Suite 11g already. We’re fairly sure that’s got a message queue in it.
Oracle plans to license GlassFish Enterprise Server and Java System Web Server with all WebLogic Server offerings.	See above.
GlassFish also available as standalone offering.	Are you sure you didn’t mean to say “Weblogic”? No? Can you call back next Thursday at 2pm and ask for Fred? We’re reasonably certain he might know something about that Glassthingy.
GlassFish will continue to be supported and maintained for an extended time period for customers current on support.	Well, the lawyers said we had to. We know how to do this. Ask any 10g customer.
GlassFish open source projects thrive	As long as we will let them.

I know I’m a completely cynical bastard about these things, but I will wager within a few months that even if you deliberately ask for Glassfish Enterprise directly that you’ll have to fight off the Weblogic borg absolutely tooth and nail to the last man as they repeatedly try to board your IT department brandishing their integrated-wizard-driven Red Stack. I predict that, basically, after a year of not even trying to sell any Glassfish licences – because if you ask for any of the features that are in the licenced version and not the open-source one, you’ll be pushed to Weblogic (and anyway, at ten times the price they’ll prefer to sell you Weblogic as a default position, after all “Glassfish comes free with Weblogic”) – Oracle will announce, “there’s no sales in it”, then probably ditch the licenced Glassfish version completely, leaving only the open source version. Finally sometime after that they’ll cut the open source funding off and it will have to limp along without hardly any of the resources it formerly had. Maybe they’ll donate it to the ghetto of an Apache incubator project where it can die unnoticed a couple of years after that. It’s a pity because IMHO Glassfish is ten thousand times a better app server than anything Oracle ever produced, or even bought before this.

The science of the architect depends upon many disciplines and various apprenticeships which are carried out in other arts. His work consists in craftsmanship and technology. Craftsmanship is continued and familiar practice, which is carried out in the hands in such material as is necessary for the purpose of a design. Technology sets  forth and explains things wrought in accordance with technical skills and method.

So architects who without culture aim at manual skill cannot gain a prestige corresponding to their labours, while those who trust to theory and literature obviously chase a shadow and not reality. But those who have mastered both, like men equipped in full armour, soon acquire influence and attain their purpose.

M. Vitruvius Pollio,   De Architectura Libri Decem, 1.1.1-2. (approx 31 to 27 B.C.)

Collection mapping is one of those “hello world” problems. (The “hello world” example in the doco looks totally trivial and completely ideal [which is the problem], but suck-in-the-galaxy-greet-it-and-then-map-all-the-stars problem, which is more like what your real app looks like, is far less than trivial and not so easily achieved with the demonstrated toolkit). In my experience, collection mapping is the cause of all sorts of pain and performance perfidy.

Here’s a further situation where I find that they really get in the way. Consider integration with existing systems that use highly-normalised database schemas (designed by advanced SQL programmers who know what they are doing in that language).

This is not an uncommon scenario – we have this system ‘A’ which (let’s say) has all our customer shipping, product, warehousing data in it. We don’t want to replace it. But we need to extend it so that e.g. available to web systems. Or maybe it needs to be integrated into the big fancy off-the-shelf CRM we’re installing. Something like that. We need to build some sort of service layer around this system ‘A’ so that other systems can access its data and/or functions. It’s common to think that an ORM around that big complex database schema is going to help, but in my experience, it doesn’t for many of the reasons Stephan and Aldo list. That sort of highly-normal database schema in my experiences completely kills ORM object representations stone cold. You end up with so many LazyInitialisationExceptions and various other problems it sucks productivity out the developers and performance out of the system.

Also, I get a bit annoyed about ORM abstractions leaking into the web tier, this is especially prevalent with using annotations rather than ORM mapping files.

Different sorts of approaches are sometimes needed to be applied with careful thought in that scenario. Perhaps you need to model the “intermediate” domain you need directly, and then use, for example, simple DAO layers which operate directly on the domain you’ve defined. These DAO layers then might call functions (stored procs) in the database that do the problematic mapping in an efficent relational language (after all it’s the direct representation of the target data format).

I’m not saying that you have to do the above in every case, or that an ORM is always wrong, but anyway the point is, ORM isn’t a magic bullet like any other technology you have to consider carefully. Your application doesn’t always need one by default.

In recent times I’ve seen this often enough that I think it’s really a failing of the IT industry in general, and we need to educate business IT users about the various scenarios and categories of software.

The simplest analogy I can think of is to say the website or portal is the letter, and the platform is the word processor.  Regardless if you use Word, Wordperfect, Pages 09, your email program or just plain old ‘notepad.exe’, at the end of the day the time to write the letter is pretty much the same effort and therefore the task is basically identical. If you said “I want you to help me to write a letter to my member of parliament”, should  I ask you whether you’re using the new letter wizard in Word? Have you seen this great “clippy” feature? Have you considered the new upgrade to Office 2007? Tell you to buy a Mac? Or would I be better off asking who is your member of parliament and what’s the matter about? When we get these sorts of naive clients we need to concentrate their minds on what their actual problem is and the best way we can solve it, when they’ve got their head in the sand thinking about that great drag-and-drop wizard feature the vendor showed them they totally thinking about the completely wrong thing.

I was off the client site so I couldn’t rely on a fast connection to their development databases. I just wrote a dummy function that was called the same as the real function with the same input and output parameters and instead of the complex function body it just wrapped a simple mock table of test data. Problem solved, Oracle XE to the rescue. But first you have get Oracle XE running on your Mac, this is what the rest of this article is about, because you can’t just download an Oracle XE edition for the Macintosh.

Virtualisation is great – use a Linux VM

However modern Virtualisation is your saviour. Put simply, you can use a virtualisation tool like Parallels, or my choice, VMWare Fusion, to run a virtualised version of Linux that contains the Oracle XE instance.

Because VMs can waste a bit of your local resources, luckily there is a specialised version of Ubuntu designed for running as a virtualised machine of this type. Its called JeOS (pron. Juice, apparently). It doesn’t have an X-window environment, just the shell, so it’s pretty lightweight and can run, with Oracle XE, in less than 512MB of memory. Perfect for getting a copy of Oracle XE onto your Macbook Pro.

It will however, eat up a couple of gigabytes of disk space, up to the maximum limit you choose for your disk size in the VMWare configuration. However it will only use the current amount of disk needed, as VMWare will expand the size of the image as needed (I’ll just assume that Parallels does something similar).

Setting it up – basic instructions

This page here – has a great set of instructions for getting JeOS installed and configured with Oracle XE on it. Follow the instructions there exactly – but only to the point where you install and configure Oracle XE – don’t go further than that.

Make sure you configure plenty of swap space as outlined in the instructions.

Setting it up on standard Ubuntu/Debian

If you are running a full Ubuntu or other Debian based instance, the instructions are somewhat simpler. Install it as per normal in your VM. But make sure your swap space is twice the memory you have assigned to the VM! Oracle XE demands things to be like that.

Add

deb http://oss.oracle.com/debian unstable main non-free

to /etc/apt/sources.list and then:

$ wget http://oss.oracle.com/el4/RPM-GPG-KEY-oracle  -O- | sudo apt-key add -
$ sudo apt-get update
$ sudo apt-get install oracle-xe

These instructions were cribbed from here.

After installing and configuring Oracle XE

After you run the XE configuration (‘$’ represents the Unix shell prompt and should not be typed);

$ sudo /etc/init.d/oracle-xe configure

If you’re running on JeOS don’t yet make the machine “headless”! Or you might find there are issues with the “Apex” application. The problem is that the Apex application, which is a useful web-based administration program for Oracle XE (especially for developers who don’t want to be forced to use sqlplus for all their database administration), will only allow connections from localhost – and you don’t have X-window, or a browser, to access it (I don’t know if lynx will work with Apex and I wasn’t going to try).

Get SSH installed

First get SSH installed in JeOS so you can get to the command prompt remotely:

$ sudo apt-get install ssh

Find out the VM’s IP address

Now, if you type ifconfig (/sbin/ifconfig if that’s not found on your path) you will be able to determine the IP address of your VM running on your Macintosh. At this point you can connect to the VM using ssh from a Macintosh terminal window:

$ ssh username@ip_address

Actually, at this point you can go ahead and make the machine headless, if you want. I would recommend not to do that until you’re sure of everything you’ve configured.

Configure environment to run sqlplus

After you’ve logged back into the running Linux VM using ssh from the Mac Terminal, the next thing is you’ve got to get sqlplus access working to the XE instance you installed. Funnily enough, although the .deb file that is installed off the Oracle site creates an oracle user, it doesn’t in any way set that user up so you can use the command line tools. SO you can’t just su – oracle and get a functional environment.

Anyway, you will need to do two things to your environment; add the ORACLE_HOME environment variable and set up your PATH so it can find sqlplus.

$ export ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server
$ export PATH=${PATH}:${ORACLE_HOME}/bin

You should add these two lines to your .profile or .bash_profile file – probably best for the ‘oracle’ user that the installation will have created. But you can actually set this up for any regular user that you configure in this VM. You can also just type them at the command line to get them in your current environment, if you have to.

Configure Apex to accept non-localhost connections

The web-based administration software for XE, called “APEX”, only binds to localhost. This is a big hassle if your VM copy of Linux (like JeOS) doesn’t have a GUI, because you don’t have a browser (lynx/links excluded, I did not try those!).  However, you can make Apex bind to the “external” IP address for your VM, but you’ll need to use sqlplus.

To run sqlplus, do the following:

$ sqlplus system@XE
  Enter password:

Enter the password you specified at the ‘oracle-xe configure’ step above.

At the SQL prompt, enter the following command:

SQL> EXEC DBMS_XDB.SETLISTENERLOCALACCESS(FALSE);

Now you’ll have to stop and start Oracle to make the configuration active:

$ sudo /etc/init.d/oracle-xe restart

After which, if you type

$ netstat -tna

You should find a line

tcp        0      0 0.0.0.0:8080            0.0.0.0:*               LISTEN

This indicates a process is listening to the port 8080 on all IP addresses for connections coming from any other IP address. Assuming you specified port 8080 at the ‘oracle-xe configure’ step. Sometimes I use 8888 especially if I have a Tomcat instance in the same VM, as Tomcat will also like to run on 8080 and I’d prefer it if it did.

Test and use Apex

Test this connection in your browser, in my case, the address was 10.1.2.17, but you will have to substitute your own VM’s IP address – http://10.1.2.17:8080/apex. I like to make an /etc/hosts entry that points to this address as ‘oracleXE’. That way I can use a symbolic name in my jdbc connection strings and actually switch which instance of XE I am using depending which VM I’ve fired up without editing the jdbc configuration of the application under development – I just change the /etc/hosts entry instead.

Anyway once you connect to apex you can login using the user name and password you set up during your XE install and configuration process (same as you used for sqlplus). The users will be sys and system, you can use them to create new users to contain your databases for development.

The same IP address as above will be used to connect to your Oracle database from the programs you are developing. The default port should be 1521 and the SID should be XE.

Enjoy!

The basics of Tapestry is that it is a component-based web framework. Just about everything, including web pages, are components. Components may contain other components. The way it works is very simple and quite elegant, once you get used to it and weaned off the big-XML-file style of configuring a web application.

When you start, you have two main Java packages that are created for you (if you use the maven archetype, otherwise you will create these packages yourself). If your package root is say “net.crazymcphee.webapp”, then your two packages are “net.crazymcphee.webapp.pages” and “net.crazymcphee.webapp.components”. To configure a Tapestry 5 project with maven use this command and answer the prompts:

mvn archetype:generate \

    -DarchetypeCatalog=http://tapestry.formos.com/maven-snapshot-repository

Don’t use the one in the tutorial as it will not work! This is an excellent illustration of the first and most serious problem that Tapestry 5 has: the documentation not only has massive lacunas, it is also sometimes wrong and not updated.

Now, any class that you create in the “pages” package will automatically become a page in your application. But these classes need not be very complex at all. For example:

package net.crazymcphee.webapp.pages;
 
import java.util.Collections;
import java.util.List;
 
import org.apache.tapestry5.annotations.Persist;
import org.apache.tapestry5.annotations.Property;
import org.apache.tapestry5.ioc.annotations.Inject;
 
import net.crazymcphee.webapp.model.Person;
import net.crazymcphee.webapp.services.PersonService;
 
public class Persons {
 
    @Inject
    private PersonService personService;
    @Property
    @Persist
    private List persons;
    @Property
    @Persist
    private String searchTerm;
 
    Object onSubmitFromSearch() {
        persons = personService.findPersons(searchTerm);
        return this;
    }
 
    Object onSubmitFromClear() {
        persons = Collections.EMPTY_LIST;
        return this;
    }
 
}

You can see that this class doesn’t extend any infrastructure classes and has quite a simple structure. This is a fully functional page with two actions – one populates a list, the other clears it.

Now, to explain just a little here; PersonService is injected by Tapestry, but you need to configure in your AppModule which implementation you want to use. You can also use it with Spring as your IOC container but the one that comes with Tapestry is perfectly good enough for most applications.

The List, persons, and the searchTerm parameters are marked as @Property (so we don’t need to add getters and setters) and also @Persist so that the variables are preserved from request to request.

The methods “onSubmitFromSearch” and “onSubmitFromClear” are using a convention – “onSubmit” will also work, but assuming (as is true in this case) that we may have multiple forms on the one page, each method will only be fired from the “search” form in one instance, and the “clear” form in the other. These names are not special, it’s just (as you’ll see below) the forms will have these two names. They could be “Bill” and “Ben” in which case the methods would be “onSubmitFromBill” and “onSubmitFromBen”.

You will also note that these methods return the same page instance, which tells Tapestry to re-render the same page, but if you wanted to forward onto another page, you would add a instance variable, mark it with an @InjectPage annotation, and return that instance variable (after initialising it in your “onSubmit” method) instead of just returning “this”.

This page Persons, is available at {application-context-path}/persons. But there is one other part of the puzzle – the actual view. As mentioned, Tapestry uses convention over configuration and in this case, the convention is that the Page markup must be named the same: Persons.tml. Here is the matching tml file for the class above;

<html t:type=“layout” title=“Peoples I Might Know”

t:sidebarTitle=“Current Time”

xmlns:t=“http://tapestry.apache.org/schema/tapestry_5_1_0.xsd”

xmlns:p=“tapestry:parameter”>

<!– Most of the page content, including <head>, <body>, etc. tags, comes from Layout.tml –>

<t:form t:id=“search”>

<t:textfield t:id=“searchTerm” validate=“required” size=“20″/>

<t:submit t:id=“searchPeople” value=“search”/>

</t:form>

<t:grid source=“persons”/>

<t:form t:id=“clear”>

<t:submit t:id=“clearPeople” value=“clear”/>

</t:form>

</html>

Yes, it’s that bloody simple. The first form fires the “onSubmitFromSearch” method (with a little bit of validation, done in javascript) and the second method clears the list. In-between, there is this <t:grid source=“persons”/> business, which, if the ‘persons’ variable in the page class is populated, will show a list of its contents!

To test our app, we can use the command-line ‘mvn clean jetty:run’. When Jetty has run up, then we can point our browser at the web app: http://localhost:8080/sample-webapp/Persons, and with any luck we will see the following:

Now, by default, Tapestry creates the web app to use the template design as shown above. Of course, you can make it look completely some other way – or even use a totally different template if you want. The page template is just a component that’s included.

So if you enter in a search term and click the search button, you’d expect to see a result like this:

As you can see, the list is automatically populated with the details returned from the service method (in this particular instance, this are just a canned response, but normally of course they’d be the result of a database or a web service call of some type).

When you click the clear button, the list is cleared as you’d expect:

Now, here’s a really powerful feature I find in Tapestry. Let’s say our automated acceptance tests assert that when the ‘Clear’ button is pressed, the Search box as well as the persons list is cleared. What Tapestry allows us to to do, is keep Jetty running, edit the files in the IDE, and re-run the tests against the running app without restarting! We edit our method:

    Object onSubmitFromClear() {
        persons = Collections.EMPTY_LIST;
        searchTerm="";
        return this;
    }

In this case I’ve also added a bit of space around the clear button in the template as well:

And now our failing test will pass.

Editing files like this in the running web app only works for Pages and I think Components. If I had to change the service or model classes I’d have to restart, but “mvn jetty:run” isn’t very a heavyweight process.

As I said above, Tapestry’s not perfect: it’s major flaw is the poor documentation. Convention-over-configuration is easy to grok – if you know the convention. If you don’t and the documentation doesn’t tell you, and you can’t find a sample of what you need, it can be very frustrating. There is an excellent user list though.

Its other major flaw may be the stability of the API. Tapestry 5 is different (and incompatible) from Tapestry 4 is different from Tapestry 3. But so far I’ve used it on a couple of projects and I’m really enjoying it. I really hate the oodles of XML boilerplate and massive amounts of configuration found in Spring and I find myself somewhat reluctant to use it unless I really have to. Tapestry solves for me a range of different problems and mostly it presents a very elegant way to create a componentised web application. You might like to give it a try.

Attached is the sample code used above. It took me about 10 minutes to write (far shorter than it took me to write this blog entry!) - sample-webapp.tar bundle