How to create and use Java Card library packages?

Question

As you may know, and as it is mentioned in Java Card Development Kit User Guide, the key to writing large applications for the Java Card platform is to divide the code into individual package units. The most important limitation on a package is the 64KB limitation on the maximum component size. This is especially true for the Method component: if the size of an application’s Method component exceeds 64KB, then the Java Card converter will not process the package and will return an error.

So, we need to use Java Card library packages in some special cases. My question is how to create and how to use these Java Card library packages?

What am I did so far?

Well, I wrote a really simple Java Class containing a single method named sayHello() as below:

package libPack;

import javacard.framework.*;

public class mylib {
    public static final byte[] hello = {(byte)'H',(byte)'e',(byte)'l',(byte)'l',(byte)'o'};

    protected mylib() {
    }

    public void sayHello(APDU apdu) {
        byte[] buffer = apdu.getBuffer();
        Util.arrayCopyNonAtomic(hello, (short)0x00, buffer, (short)0x00, (short)hello.length);
        apdu.setOutgoingAndSend((short)0x00, (short)buffer.length);
    }
}

As I couldn't find any option in my IDE-s (Netbeans & Eclipse) to create cap file of library packages (Those have plugins for creating cap from Applet packages only, I guess), I used command line to create my library's cap file as below:

1. Generating the .class file of above .java program:

CMD:> javac -g -source 1.2 -target 1.2 -cp "D:\JCDK\java_card_kit-2_2_2\lib\api.jar" "D:\LibSrc\mylib.java"
warning: [options] bootstrap class path not set in conjunction with -source 1.2
1 warning

CMD:>

Above command generate a .class file that its name is my library class name. I create a folder in the same directory and named it "libPack" (the program's package name) and then I moved this .class file into it.

2. Converting the created .class file to .cap file:

CMD:> D:\JCDK\java_card_kit-2_2_2\bin\converter.bat -debug -verbose -exportpath D:\JCDK\java_card_kit-2_2_2\api_export_files -classdir D:\LibSRC libPack 0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x6:0x1 1.0

Java Card 2.2.2 Class File Converter, Version 1.3
Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.

parsing D:\LibSRC\libPack\mylib.class
converting libPack.mylib
parsing D:\JCDK\java_card_kit-2_2_2\api_export_files\java\lang\javacard\lang.exp
parsing D:\JCDK\java_card_kit-2_2_2\api_export_files\javacard\framework\javacard\framework.exp
writing D:\LibSRC\libPack\javacard\libPack.exp
writing D:\LibSRC\libPack\javacard\libPack.jca

conversion completed with 0 errors and 0 warnings.

CMD:>

Above command, generate libPack.cap and libPack.exp files in "libPack\javacard" directory.

Questions:

1. Am I did the Java Card Library Package generation process in a right way?
2. How can I use this library package in my applets to reduce my applet packages smaller in size?

---

Update: (Based on dear Vojta's answer)

To make whole the process IDE-Independent, I create a .jar file of my library .class file using the following command in the commandline again:

CMD:> jar cfv mylib.jar D:\LibSRC\libPack\mylib.class
CMD:>

The above command, created "mylib.jar" from the "mylib.class" file in the command line current directory.

After that I added this "mylib.jar" file and its already created .exp file (previous step using Converter) to my Applet project in Netbeans IDE, in the same way that I explained here.

Now I want to use the sayHello() method of my library in my applet:

As you see above, I still receive an error. What's that? As far as I know, I can't define static methods in the library packages (right?), so where I can use library methods?

Answer 1

Any Java Card package with some public classes and public methods can be used as a library. If you use Eclipse JCOP Tools, you can build your library very easily: the cap file is created automatically in folder:

/[workspace]/[project]/bin/[path according to package]/javacard

A Java Card library is just any package; even a package with an Applet can be used as one. So there is no real difference between building a "common" cap file and a "library" cap file.

---

Note there is a little difference between objects implementing Shareable interface and static methods in your library package. Shareable interface can be used to access object instances in context A through the firewall from the context B. However, static methods can be accesses from any context - no firewall rules apply. There is a nice overview of AppletIsolation and Object Sharing here. The most important paragraph on static methods is 6.1.6:

Instances of classes—objects—are owned by contexts; classes themselves are not. There is no runtime context check that can be performed when a class static field is accessed. Neither is there a context switch when a static method is invoked.

Public static fields and public static methods are accessible from any context: static methods execute in the same context as their caller.

Objects referenced in static fields are just regular objects. They are owned by whomever created them and standard firewall access rules apply. If it is necessary to share them across multiple contexts, then these objects need to be Shareable Interface Objects (SIOs).

Of course, the conventional Java technology protections are still enforced for static fields and methods. In addition, when applets are installed, the Installer verifies that each attempt to link to an external static field or method is permitted. Installation and specifics about linkage are beyond the scope of this specification.

Shortly speaking: no static objects in your static library = no Shareable needed.

---

You sometimes need to use an existing library in your new applet, although you do not have the source code of the library. The library might have been loaded to your card by the vendor or by some third party. You need a jar file and an exp file of the library to be able to use it in your applet.

You need class files of the library in a common Java jar file to build your new class files by the Java compiler. Then you need some extra information for the Java Card Converter to link your code with library classes and their methods. That is what exp files are used for. The exp file describes the interface and dependencies of all public components in a cap file. Eclipse JCOP Tools creates the exp file together with the cap file in the same folder, as well as the Java Card Converter does. (See the documentation by Oracle)

The exp file and the jar file is all you need to build your code which uses the library. Just put them both into your project and make sure the jar file is on the build path of your project.

Feel free to ask.