Recently we extended our enterprise search engine bleen adding a desktop utility automatically launched clicking on a result link.

To achieve this we created a native applciation ( for windows and osx ) registered to the protocol url bleen://

In this tutorial we will see how to build this utility in Java for Mac OS X.

The base code is a simple java class displaying a Dialog

Application bundle

Creating a OSX application bundle is as easy as creating a directory structure following some simple rules.

Out directory tree will contain :

  • a jar with out classes
  • the dependency jars
  • the info.plist file
  • a native executable  

The following is a ant tast that creates the dir tree.


<target name="application-bundle" depends="jar" description="create mac Os X Application bundle">

    <mkdir dir="${dist.appbundle}/Contents/MacOS" />

    <mkdir dir="${dist.appbundle}/Contents/Resources/Java" />

    <copy file="${auxes.dir}/JavaApplicationStub" todir="${dist.appbundle}/Contents/MacOS" />

    <exec executable="chmod">

        <arg value="755" />

        <arg value="${dist.appbundle}/Contents/MacOS/JavaApplicationStub" />


    <copy file="${auxes.dir}/Info.plist" todir="${dist.appbundle}/Contents" />

    <copy file="${auxes.dir}/icon.icns" todir="${dist.appbundle}/Contents/Resources" />

    <copy file="${dist.dir}/application.jar" todir="${dist.appbundle}/Contents/Resources/Java" />

    <copy file="lib/libreria1.jar" todir="${dist.appbundle}/Contents/Resources/Java"/>

</target> <br>


The result is a directory tree viewed ad a application document by OSX.

URL protocol

The application runtime information are stored in info.plist file.

We edited this file inserting a couple of new keys. These keys link out app to the protocol demo://

  • URL Types
  • URL Identifier
  • URL Schemes

Now, the system will launch our utility every time the user clicks on a link starting with demo://

To allow osx to know out utility exist we must :

  • copy the app to /Application directory
  • or manually launch it at least once 


Now we reached our target but we don’t use the clicked url in our code, yet. 

To use it, we must relay on a system event osx raises to ask applications to manage urls. We use an extension library provided by Apple, registering a handler to the OpenURI event. 

public static void main(final String[] args) {


        new OpenURIHandler() {


            public void openURI(final OpenURIEvent pEvent) {

                JOptionPane.showMessageDialog (









Note that our dependencies jar must be located in Contents/Resources/Java and every jar must be declared in Info.plist under the keys Java/Classpath


You can find a demo project download on our public space in Assembla - link


Handling URL shemes in Cocoa



MRJAdapter - java library to enhance osx integration

Apple doc - References to the java info.plist keys

Apple doc - References to application bundles creations

Apple javadoc - Javadoc for Apple Java extensions




1 Comment