I recently have been learning a number of different APIs. After reflecting on my process for learning I have ended up with the following strategy for working with APIs.

1. Find someone who has used the API in the past and get a brief introduction.
2. Read documentation about the product (starting at the central documentation site for the product, include any tutorials and getting started guides). The goal from this first step is to get a general background understanding of what the product is about, the core concepts and jargon and principles of the product.
3. Use the product without the APIs. If there is a gui to access to product that is available, ensure that you know this, and the jargon around the product. Try and ensure that the information you have from step 1 is grounded in reality.
4. Read more documentation around the APIs. Make the top goal for this round to get enough of an understanding of what you can do.
5. Explore the APIs to see what they expose of the feature. The set of features exposed by APIs often do not match up with what is exposed through the GUI. The most important spot to aim for is the subset of features that are supported by both the API and the GUI.
6. Google (as usual it’s your friend). Sometimes there are some useful results in google that are missed elsewhere. Start with searching for the product name, try adding in API/howto/tutorial/getting started keywords to filter down content if you get too many results.
7. Write some exploratory code to see how the APIs work, and what they do. This should enable you to know enough to actually write the code that you need.

All steps are required, as there are often features which are not easily discovered by just taking one of the above paths. One of the most important steps is ensure that you do understand the subset of what is supported by the API and the front-end. This helps to ensure that you are actually hitting the right part of the API.

From time to time there are options which are not well documented at all, and are only alluded to in technical documents. It can be worth contacting authors of documents if the feature is not clear. The coding and exploration of the system will need to continue after this. It should be expected to continue learning the APIs. At every stage there is value in talking to whatever experts/more experienced people you have available. Being able to quickly pickup a technology and move from no knowledge to confidence in using the API is a valuable tool for developers. Learning new technologies has been an important part of my job as a software engineer, and I expect that it will continue to be for many years to come.

I’ve recently started using the TestDox plugin with IntelliJ. It’s a nice little tool that fits in well with agile test driven development practices. It’s easy to get started with, either installing it from the IntelliJ plugins repository using your IDE, or downloading it directly from the plugins repository, and copying it into the plugins directory.

The premise on which the test dox plugin is based on is the idea that your test methods should be long sentences using CamelCase to break up words. By doing this your tests become your documentation. The plugin takes this premise, and exposes the following behaviour in IntelliJ:

1. automatic translation of CamelCase test names to sentences. This is exposed through two different views, which, when coupled with nice navigation synchronisation options, makes it possible to use your tests to understand what the code is meant to do at a high level, and makes it easy to drill down to the specifics when needed.
2. There is a simple mapping between classes and tests – TestDox knows that HelloWorldTest is the test for HelloWorld. This is configurable to suit your environment (test classname prefixes and suffixes can be specified, as well as test packages).
3. documentation windows will be context sensitive, using the above mapping to show the appropriate documentation for the class/test currently being edited.
4. alt-shift-t swapping between the test class and the base class – great for navigation
5. alt-shift-t will prompt to create a test class if it doesn’t exist. Very cool fr the cases where you have created a class before the test (for whatever reason)

Overall this is a great little tool. There’s only a couple of minor tweaks I’d like to see made to the tool.

1. The biggest that would be nice for the open source project, would be to make editing the source code of the IntelliJ plugin slightly easier. It would be cool to be able to make slight changes to the software, and help improve the project, but the cost of entry was slightly too high for me.
2. It would be good for the alt-shift-t auto creation to work both ways. That is I want alt-shift-t to help me automatically create the class as well as the test.
3. I saw a couple of minor screen repaint issues on 7.0.3 on OSX 10.5

TestDox is a good tool for IntelliJ, and you really should install it and use it.

I have been working with different ideas for Test Driven Swing code for a while now. Recently, Suneth and I came up with a new strategy for testing Swing BorderLayouts (unfortunately requiring reflection).

Here is what we did.

When using a border layout you are specifying the relative position of the components. To TDD this, you really want to say whether your component appears in the NORTH, SOUTH, EAST or west location.

Unfortunately this isn't exposed directly, hence the need for reflection.

Here is the method that we wrote to do this:

private JComponent getComponentAt(BorderLayout layout, String position)
    throws NoSuchMethodException, IllegalAccessException, InvocationTargetException {
  Method method = BorderLayout.class.
    getDeclaredMethod("getChild", new Class[]{String.class, boolean.class});
  method.setAccessible(true);
  return (JComponent) method.invoke(layout, new Object[]{position, Boolean.TRUE});
}

The layout is the layout containing the component, and the string position needs to be one from the BorderLayout constants (BorderLayout.NORTH etc).

The method will retrieve the component at the specified position using reflection, allowing you to write simple assertions around this.

One of the features I like about TextMate is the smart insertion of characters, like when I’m typing text, highlight a word, and type ", TextMate will wrap the word in quotes. Unfortunately IntelliJ doesn’t have this behaviour by default, and makes surrounding some text in quotes messier than what would be preferred.

It is possible to make this task much easier, through the use of live templates. Here is how to do it.

1. navigate to the add a live template screen via the following path: settings – live templates – add
2. type "$SELECTION$" as the template text, ensure that the context is suitably broad, give it a meaningful name, and you are done. This can be seen in pictures.

You will now be able to access the template using the cmd-option (ctrl-alt) t "surround with" shortcut, making it easy to wrap text (code) in quotes using IntelliJ.

As a part of my test suite, I run a series of tests using Hibernate and the h2 database (h2 seems to be the most lightweight java in memory database around at the moment). These tests run in memory and perform realively quickly, so are a part of my pre-commit build.

In order to move to a spot where the application upgrades work well, I’ve just removed the hbm2ddl.auto create-drop statements from my hibernate.xml file, and wanted to move to a programmatic use of the SchemaExport tool. This was more pain than expected, so I’m documenting what I had to do here.

From the javadoc, and Java Persistence with Hibernate, it looks like you can get away with the following code:

1: Configuration configuration = new Configuration().configure();
2: SchemaExport schemaExport = new SchemaExport(configuration);
3: schemaExport.create(false, true);


Unfortunately I found that this didn’t quite work. It seems that the connection/transactionality/connection pool combination of concerns would cause this kind of code to fail at various degrees. After much gnashing of teeth I ended up with the following code:

1: Configuration configuration = new Configuration().configure();
2: SessionFactory sessionFactory =
         configuration.buildSessionFactory();
3: Session session = sessionFactory.openSession();
4: Connection connection = session.connection();
5: SchemaExport schemaExport =
          new SchemaExport(configuration, connection);
6: schemaExport.execute(false, true, false, true);
7: session.close();

the critical differences are:

In lines 2-4 we are obtaining a connection to the database which is then used by the schema export tool. In line 6 we do the export using the execute command, passing in a bunch of booleans. This tell it execute command:

• don’t output the sql to the console,
• do execute on the database,
• don’t execute drop statements, and
• do execute create statements.

Finally in line 7, we close the session, ensuring jdbc connection is released and cleaned up. Now any intermittent problems caused by using schema export with h2 database should be avoided.

Having an automated deployment procedure is an important goal for any project. This post talks about the the steps taken in making E2 autodeploy to WebSphere Portal in Development.  The below process assumes that the application has been deployed once through other means.

After a friendly pointer from AJ to an article about automating websphere deployment, I decided that the time had come to revisit trying to automate the deployment of our EAR file for E2. I had done bits and pieces of thi in the past using a combination of the WebSphere scripting client, and the WebSphere ant tool (like ant but built with WebSphere bits and pieces). The killer constraint for me is that my client machine didn’t have access to any of the WebSphere binaries (perhaps unsuprisingly Apple and IBM have don’t perfectly interoperate).

In order to work around thi sproblem I ended up leveraging one of the classic protocols (telnet), the websphere scripting client, samba (to mount the application server drives), and a bit of ant to glue it all together. The process outlined below is focused around the deployment of the application E2Application to WebSphere portal.

Step 1: Enable telnet

In Windows Server 2003 this is relatively straightforward. Simply go to your control panel -> services -> Telnet go to the properties, make it automatic and start it.

Step 2: Write scripts to start and stop the app server

I did this using tcl and ended up with the following scripts (the pythonistas may like to use jython to do the same):

stopApplication.jacl  

set cell [$AdminControl getCell]
set node [$AdminControl getNode]
set appManager
   [$AdminControl queryNames
   cell=$cell,node=$node,type=ApplicationManager,process=WebSphere_Portal,*]
$AdminControl invoke $appManager stopApplication E2Application


startApplication.jacl  

set cell [$AdminControl getCell]
set node [$AdminControl getNode]
set appManager
    [$AdminControl queryNames
   cell=$cell,node=$node,type=ApplicationManager,process=WebSphere_Portal,*]
$AdminControl invoke $appManager startApplication E2Application


Step 3: Write the ant code to compile and copy the application

After the series of standard building tasks, we used a simple copy task to copy the files to the exploded WAR directory on the server. (something like: ${portal.home}/WebSphere/profiles/wp_profile/installedApps/{cell}/{application}.ear/{app_war}.war). Since I develop on a laptop I added in a combination of available and fail task to stop me from accidently creating directories if I hadn’t mounted m

Step 4: use ant to telnet to the server

Make use of the telnet ant task1 to telnet into the server, and run the stop and start server jacl scripts. My Ant targets (passwords scrubbed) are below (excuse the duplication):

<target name="startApplication">
   <telnet userid="Administrator" password="${portal_admin_password}" server="${portal_server}">
   <read>Administrator</read>
        <!– change to the IBM AppServer directory –>
        <write>cd \ibm\AppServer\bin</write>
        <read>AppServer\bin</read>
        <!– Execute the jacl –>
        <write>wsadmin -conntype SOAP -port 10033
                -username wasadmin -password **** -f startApplication.jacl
        </write>
        <!– wait for the connected to process message, which will occur on the successful completion of the script –>
        <read>Connected to process</read>
        <read>AppServer\bin</read>
    </telnet>
</target>


<target name="stopApplication">
    <telnet userid="Administrator" password="${portal_admin_password}" server="${portal_server}">
        <read>Administrator</read>
        <!– change to the IBM AppServer directory –>
        <write>cd \ibm\AppServer\bin</write>
        <read>AppServer\bin</read>
        <!– Execute the jacl –>
        <write>wsadmin -conntype SOAP -port 10033
                -username wasadmin -password **** -f stopApplication.jacl
        </write>
        <!– wait for the connected to process message, which will occur on the successful completion of the script –>
        <read>Connected to process</read>
        <read>AppServer\bin</read>
    </telnet>
</target>

Step 5

mix ingredients and enjoying being able to have a one click deploy to WebSphere Portal.

Appendix

For security paranoid people with time on their hands, it is possible to do this using ssh and scp. The key parts will be step 3 and step 4. In step 3 we are using folder share and the ant copy task currently. It could be done with scp. In step 4 the use of telnet could be replaced with ssh.

1 - The telnet task depends on the availability of the commons-net jar on the classpath. (click here to download commons-net).↩

In order to make the Oracle XE database work with IBM WebSphere Portal IWWCM there are a number of steps to perform.

1. Ensure that the database is accessible using the Oracle SID (see the early post Oracle SID!=Service name)
2. Next you will need to increase the number of proceses that can be connected to the instance, as there are a large number of connection pools set up by the system, which the database will need to support. The following command worked in my environment:

       ALTER SYSTEM SET PROCESSES=150 SCOPE=SPFILE;

3. After having performed these base setup commands and options, you can run the IWWCM migration scripts to migrate existing data.
4. To ensure that the connection pooling works correctly, you will need to grant the following privileges to public:

   grant select on pending_trans$ to public;
grant select on dba_2pc_pending to public;
grant select on dba_pending_transactions to public;

5. Finally, grant the following privilege to each user to which connections are made from the application server.

       grant execute on dbms_system to <user>;

After having performed these steps you will have an Oracle XE database that will work happily with IWWCM.

For the regular readers of my blog, you may be wondering why I am stepping over to the dark side, and using Eclipse. Not to fear – it is just for an Eclipse plug-in. Using the right tool for the right job is important to always do.

When recently using the SAP Memory Analyzer tool to look at a large (1GByte) hpprof output file, I was running out of Heap space, so was lookin for where to set the -Xmx and -Xms settings on Eclipes. It was somewhat harder to find than desired, and the internet didn’t tell my as quickly as I wanted, so here’s the answer (while the video at http://www.brooksandrus.com/bog_assets/screencasts/eclipsejvmheap/ was cool, a simple text blog entry would have made me happy).

The eclipse.ini file in Eclipse.app/Contents/MacOS is the file that needs to be edited. (not the one that for me was close in location /Applications/eclipse/configuration/ eclipse.ini was bad, /Applications/eclipse/Eclipse.app/Contents/MacOS/ eclipse.ini was good).

After finding the right eclipse.ini, setting the memory is straightfoward. Simpley update the -Xmx and -Xms settings (see: The Sun Tuning java guide for what these do if you don’t know).

BeanShell promises lightweight scripting for Java. Support for BeanShell is included with the Apache ant build tool, and it is targetted to be included as a part of the standard edition of Java with JSR-274. I’ve recently included BeanShell in a project, and will share what I have achieved with this, and some of the motivations and considerations when doing this.

My primary reason for adding BeanShell was that we use some heavy enterprise APIs. We are able to mock these out for development, but have experienced consistent issues when working with the APIs, primarily caused by missing or misleading documentation. This means that there is often a need to write code to understand the APIs. To deploy to the application server takes about 3 minutes, and the wrestling required to make the code work is often much more painful that expected. It is pain which motivates the creation of some nice tools, and this pain motivated the creation of a simple tool using BeanShell.

In it’s simplest form, the tool allows the execution of code on the server that has been input into a text area. This is a powerful tool for developers and admins, but is somewhat (ok very) risky from a security standpoint, and needs to be treated as such.  Getting BeanShell up and running is really straightforward.  I've only got a couple of recommendations and comments to make about doing so.

1. Integrating BeanShell itself is really straightforward. Simply have a servlet (action/jsp/whatever) which reads in a request parameter, uses an instance of the beanshell interpreter class to eval the string. The quickstart guide makes it clear and easy to get started (makes it quick to start ).
2. In order to make the interpreter useful, you will want to have add imports of the important packages for your application (such as to your Data Access Layer), and also the set some variables on the context. Prepend the imports to the scripts before they are eval'ed, and set the variables using the interpreter set(String, Object) method.
3. In addition to the result of the script, and the application variables that I put on the interpreter, I also add in a PrintStream, making it easy to output debug information.
4. Finally, it is really useful to keep track of what statements have been executed, and the results of the statements.  Save these to the session, and list these on the page. A simple javascript function makes it possible to replace the contents of the text area with previous scripts, and also the output, and result messages.  This rounds out a simple little tool nicely.1

By doing this, it is possible to explore APIs, and work at a very quick pace. Whenever something behaves unexpectedly on the server, one can quickly explore what has happened, and produce the updates to production code, which are required to make this work. BeanShell is a powerful tool for serverside development, and well worth considering adding to your toolkit.

1 - for extra credit, it is really easy to keep a list of previous statements on the page, and use the javascript above to keep track of the history.↩

… or how to setup your Oracle XE database so that JDBC database urls will work like they traditionally have.

For many years Oracle has been telling everyone Oracle SID != SERVICE_NAME.

Java Developers have always smiled and nodded with this statement as the oracle thin client jdbc url would always be something like:

jdbc:oracle:thin:@server:1521:SERVICE_NAME, or
jdbc:oracle:thin:@server:1521:SID 

which would work because databases always either had the SID and SERVICE_NAME as the same, or there was some magic that the Oracle listeners did to make this work.

Somewhere in the past couple of releases of Oracle this transparent mapping has ceased to exist. In particular Oracle 10G XE out of the box doesn’t support this sort of option.

It seems the new preferred way of doing Oracle JDBC URLs is:
jdbc:oracle:thin:@server:1521/SERVICE_NAME.

I discovered this information while working with making a WebSphere Portal instance use Oracle as it’s data repository. The documentation for doing this suggested using the old school SID style of url.  I tried this first as it felt familiar, but things didn't work.  Changing the url to use the PORT/SERVICE_NAME approach looked to mostly work, but didn’t quite spread the changes to everywhere required. I needed to run WPSConfig connect-database to update all the hidden bits of configuration around the portal installation. Unfortunately, this failed as the wpsconfig script calls out to programs that expect the url to follow the old school syntax (the stack trace show an index-out-of-bounds exception while parsing connect srings). I then had to go in and update the configuration on the database to enable connection via the old SID style approach.

This was done by working on the listener.ora file
(C:\oraclexe\app\oracle\product\10.2.0\server\NETWORK\ADMIN) to add in a SID_LIST_LISTENER entry for the database.

This was simply to add:
(SID_DESC =
    (GLOBAL_NAME = XE)
    (SID_NAME = XE)
    (ORACLE_HOME = C:\oraclexe\app\oracle\product\10.2.0\server)
)

to the SID_LIST of the SID_LIST_LISTENER

I ended up with a SID_LIST_LISTENER that looks like this:

SID_LIST_LISTENER =
    (SID_LIST =
        (SID_DESC =
            (SID_NAME = PLSExtProc)
            (ORACLE_HOME = C:\oraclexe\app\oracle\product\10.2.0\server)
            (PROGRAM = extproc)
        )
        (SID_DESC =
            (SID_NAME = CLRExtProc)
            (ORACLE_HOME = C:\oraclexe\app\oracle\product\10.2.0\server)
            (PROGRAM = extproc)
        )
        (SID_DESC =
            (GLOBAL_NAME = XE)
            (SID_NAME = XE)
            (ORACLE_HOME = C:\oraclexe\app\oracle\product\10.2.0\server)
        )
    )

This configuration works with an out of the box Oracle XE installation, and lets me use the jdbc:oracle:thin:@server:1521:SID.