Encapsulation of Java apps: Easy as Pie!

capsulecorp

You may have seen how I “ported” many applications on the Pandora if you look at the repo often enough. Truth is, I am no true porter and it is actually trivial to run Java applications on Pandora, once you have the Java PND installed. But here’s a little explanation on how to put these little funny java apps into PND “capsules”, so that you can become a Repo King as well!

First you need to look for Java applications, packaged in .jar files. Usually you can find such applications on github, on sourceforge, google code… if you look carefully. Since we usually will not make any modification to the code and simply run the program as is, you better check as well if the application is adapted to the Pandora screen. Not too large windows, not a 3D application, etc… As long as you restrict yourself to usual applications it should be just fine. Get the *.jar file. The first thing I usually do after that is to copy the said *.jar file anywhere on my SD card, then go in the terminal and execute it with the following command:

java -jar nameofapp.jar

This will give you a good hint if the app will work well on Pandora or not, be it screen size, speed, or missing Java libraries that may prevent its execution. I would say .jar files work relatively fine about 60%-70% of the time so you better check for sure before moving to the next steps.

Then comes the encapsulation itself. Before I explain the how, I think it’s relevant to come back to the meaning of the word Capsule. No, Capsule is not only the name of a Japanese pop band whose members wear silly clothes and accessories.

capsule02

A capsule is a mean to protect something contained inside it. In the physical world, capsules are used in different situations. For example, in the pharmaceutical industry, one usually uses oral capsules in the early phases of human research in order to save time, by simply putting the active ingredient as is into a digestible plastic shell. Why save time? Well, clinical trials can take a very long time, and since time is money, one is rather inclined to start as soon as possible rather than later. Through the course of research & development, the capsule form is usually dropped in favor of tablets, which are more practical and friendly for the patient.

capsules

However there are some cases where an actual tablet formulation is really difficult to make (interactions with excipients, stability issues, or laziness of R&D people etc…) and that is when you still get medicines as capsules even in their commercial form.

So, I use the term encapsulation here, since we do not change the initial Java program at all, and we simply put a PND capsule around it to make it go through the Pandora’s digestive tract.

For the encapsulation you will need the following:

  • the *.jar file(s)
  • a PXML file
  • an icon (in png format, with transparent background)
  • a run.sh file
  • several screenshots (always nice to have for the repo)
  • and the pnd_make.sh script installed somewhere on your computer (or your Pandora)

From there on it’s easy as pie. I will let you take care of the screenshots and icon files, but for the run.sh script you will use, you should include something like the following:

#!/bin/sh
export PATH="$PWD/bin:${PATH:-"/usr/bin:/bin:/usr/local/bin"}"
export LD_LIBRARY_PATH="$PWD/lib:${LD_LIBRARY_PATH:-"/usr/lib:/lib"}"
export HOME="$PWD" XDG_CONFIG_HOME="$PWD"
export QTDIR="$PWD"

java -jar nameofapp.jar

The first few lines ensure that there will be proper redirection to the SD Card appdata to avoid writing data in the NAND, as well as looking for libraries in the PND on top of the system ones.

The last line is the one that will execute your *.jar file. Now you can save this little script as run.sh and put it in the folder with the rest.

You simply need to edit the PXML file (here is an example below) to fill in the appropriate terms. I have marked in red the sections you have to edit yourself for your app.

<?xml version="1.0" encoding="UTF-8"?> 
<PXML xmlns="http://openpandora.org/namespaces/PXML" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="PXML_schema.xsd">
<!-- please see http://pandorawiki.org/PXML_specification for more 
information before editing, and remember the order does matter --> 
<application id="idofyourapp" appdata="directorynameofappdata">
<exec command="run.sh"/>
<title lang="en_US">App Name</title>
<author name="Creatorofapplication" website="http://websiteofapplication.com"/>
<version major="X" minor="X" release="X" build="01"/>              
<!--This programs version-->
<osversion major="X" minor="X" release="X" build="01"/>                 
<!--The minimum OS version required-->
<description lang="en_US"> 
Put here a long description of the app, that will be displayed in the repo!
</description>
<icon src="icon.png"/>
<!--
<previewpics>
<pic src="01.png"/>
<pic src="02.png"/>
</previewpics>
-->
<!--<info name="Appname documentation" type="text/plain" src="readme.txt"/>-->
<categories>
<!-- http://standards.freedesktop.org/menu-spec/latest/apa.html -->
<category name="Categorynamecheckabovelink">
<subcategory name="onlyifneeded"/
</category>
</categories>
<!--<clockspeed frequency="600"/>-->
</application>
</PXML>

Then, once you are done and have put everything in the same folder, you can run the following command with pnd_make.sh (you can get it here) and you will get your nicely packaged PND. Here is the example with Jmol, where i indicate with -d the directory jmol1314 on my harddrive that contains everything, as well as the icon to use with -i and its path, and the name of the final package with -p.

./pnd_make.sh -d /home/path/jmol1314/ -i /home/path/jmol1314/icon.png -p Jmol.pnd

And you are done! Now you just need to put your PND in the /pandora/menu/ folder of your SD Card, select your app from the menu and pray that you did nothing wrong! If all goes well, it should work perfectly and you should be ready to upload your PND to the repo. And you will be on your way to become one of the famous Pandora Community contributors!

Of course, there’s more to “capsules” than just medicines and Java encapsulation on Pandora, I’ll have to tell you about these Capsule hotels in Japan that make you feel like you live in the Matrix.

capsule-hotel

But that will be for another time.

 

 

Leave a Reply

4 Comments on "Encapsulation of Java apps: Easy as Pie!"

avatar
  Subscribe  
newest oldest most voted
Notify of
Milkshake
Guest

Nice article 🙂 though that pxml used in the example is out of date you might wanna look here http://pandorawiki.org/PXML_specification#Example_files for up to examples.

Gamingmayr
Guest

pnd_make.sh says it can’t find mkisof.sh. Can you help me? Where can I get it from/find it?