<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | |
<!-- | |
Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. | |
--> | |
<html> | |
<head> | |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> | |
<title>Java Card Development Quick Start Guide - NetBeans IDE Tutorial</title> | |
<link type="text/css" rel="stylesheet" media="all" href="../../../netbeans.css"> | |
<meta name="author" content="Tim Boudreau"> | |
<meta name="description" content="Getting started with Java development on Smart Cards with the NetBeans Java Card plugin"> | |
<meta name="keywords" content="Java Card, smart card, Java, emulator, platform, netbeans plugin"> | |
</head> | |
<body> | |
<h1>Java Card Development Quick Start Guide</h1> | |
<p><img src="../../../images_www/articles/74/javacard/java-smart-card-sm.jpg" alt="A Java-ready smart card" | |
style="float:right"></p> | |
<p><em>Contributed by Tim Boudreau, maintained by Ruth Kusterer</em></p> | |
<p> | |
Java Card is an interesting platform to work with - a JVM that runs on <a href="http://en.wikipedia.org/wiki/Smart_card">smart cards</a> | |
and tiny devices that fit in the palm of your hand. As of Java Card 3.0, it comes in two flavors: | |
</p> | |
<dl> | |
<dt><strong>Classic</strong>:</dt> | |
<dd> | |
This is the same as earlier versions of Java Card. The platform is extremely limited. For example, | |
<tt>java.lang.String</tt> does not exist, there is no <tt>java.lang.Object.hashCode()</tt> method, | |
and no floating point numbers. | |
</dd> | |
<dt><strong>Extended</strong>:</dt> | |
<dd> | |
For newer, more powerful smart cards—this is new in Java Card 3.0. It supports a much more complete implementation of the | |
Java Platform. Probably the coolest thing about it is native support for Servlets—you can actually write a web application | |
using familiar APIs, which runs on a smart card! | |
</dd> | |
</dl> | |
<h3>Contents</h3> | |
<ul> | |
<li><a href="#reqs" title="Required Software and Hardware">Required Software and Hardware</a></li> | |
<li><a href="#setup" title="Getting the Project Environment Set Up">Getting the Project Environment Set Up</a></li> | |
<li><a href="#types" title="Understanding Java Card Project Types">Understanding Java Card Project Types</a></li> | |
<li><a href="#projects" title="Working With a Project">Working With a Project</a></li> | |
<li><a href="#special" title="Using Special Plugin Features">Using Special Plugin Features</a></li> | |
<li><a href="#sdk" title="Integrating Third-Party SDKs">Integrating Third-Party SDKs</a></li> | |
<li><a href="#related" title="Related Links">Related Links</a></li> | |
</ul> | |
<h2><a name="reqs"></a>Requirements</h2> | |
<p><b>To complete this tutorial, you need the following software and resources:</b></p> | |
<img src="../../../images_www/articles/68/netbeans-stamp.gif" class="stamp" | |
width="114" height="114" alt="Content on this page applies to NetBeans IDE 6.8 and 6.9" | |
title="Content on this page applies to the NetBeans IDE 6.8 and 6.9"> | |
<table> | |
<tbody> | |
<tr> | |
<th class="tblheader" scope="col">Software or Resource</th> | |
<th class="tblheader" scope="col">Version Required</th> | |
</tr> | |
<tr> | |
<td class="tbltd1"><a href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td> | |
<td class="tbltd1">6.8</td> | |
</tr> | |
<tr> | |
<td class="tbltd1"><a href="http://java.sun.com/javacard/downloads/index.jsp">Java Card SDK</a></td> | |
<td class="tbltd1">3.02 </td> | |
</tr> | |
<tr> | |
<td class="tbltd1">Java Card Plugin for NetBeans</a></td> | |
<td class="tbltd1">1.3 </td> | |
</tr> | |
<tr> | |
<td class="tbltd1"><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development Kit</a> (JDK)</td> | |
<td class="tbltd1">Version 6 </td> | |
</tr> | |
</tbody> | |
</table> | |
<h2><a name="setup"></a>Getting the Project Environment Set Up</h2> | |
<p>Since a smart card does not have a user interface, you either need a smart card reader to read and write the data on your cards, | |
or use the emulator included in the Java Card Reference Implementation (RI). This tutorial will use the emulator. </p> | |
<p><b class="notes">Note:</b> the Java Card plugin works on any operating system, but the Java Card Reference Implementation emulator | |
is only available for Windows. However, you can set it up as a Java Platform on other operating systems by pointing NetBeans to an installation | |
of the RI on a Windows partition on a Mac or Linux system, but you won't be able to run projects using this setup. </p> | |
<h3>Installing Plugins into the NetBeans IDE</h3> | |
<ol> | |
<li>Download and install NetBeans IDE 6.8.</li> | |
<li>After installation go to the Tools > Plugins menu.</li> | |
<li>Under Available Plugins, there are two Java Card-related plugins: Java Card, and Java Card Runtime Bundle. | |
<ul> | |
<li>Java Card is the plugin that adds Java Card project support to the NetBeans IDE.</li> | |
<li>The Java Card 3.0.2 Runtime Bundle is required only if you do not already have a copy of the Java Card Reference Implementation installed. | |
</li> | |
</ul> | |
<p><img src="../../../images_www/articles/74/javacard/install-javacard-plugins.png" alt="Installing the Java Card Plugin for NetBeans"></p> | |
</li> | |
<li>You need to to restart the IDE after installing the plugins to continue the tutorial steps that follow.</li> | |
</ol> | |
<h3>Registering the Java Card Platform</h3> | |
<p>If you downloaded the Java Card 3.0.2 Runtime Bundle from the Plugin Manager, the Java Card SDK is already set up | |
as a platform for you. However if downloaded and installed the Platform from <a href="http://java.sun.com/javacard/devkit/">java.sun.com</a> | |
you can use the Tools > Java Platforms menu to add the Java Card Platform to the IDE the same way as registering any Java platform.</p> | |
<p><img src="../../../images_www/articles/74/javacard/installPlatform.png" alt="Installing a Java Card Platform" ></p> | |
<p>Once you have set up the Java Card platform it is listed in the Services tab in the IDE. If the Services tab isn't visible, | |
choose Windows > Services from the menu. </p> | |
<p><img src="../../../images_www/articles/74/javacard/services-tab.png" alt="Installed Java Card Platforms and Devices"></p> | |
<p> One "platform" may have multiple "devices". You deploy a project to a specific device on a specific platform. </p> | |
<h2><a name="types"></a>Understanding Java Card Project Types</h2> | |
<p> | |
Choose File > New Project from the menu, and click the Java Card category. | |
There are several kinds of Java Card projects you can create. | |
All of them are built with <a href="http://ant.apache.org/">Apache Ant</a>, | |
just like NetBeans Java SE projects. | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/choose-project-type.png" alt="Java Card Project Types in NetBeans"> </p> | |
<p> | |
Classic Applet projects create a traditional Java Card applet for smaller devices, just like the applets used in Java Card 2.0 | |
and older. Classic library projects are like Classic Applet projects, without the applet — it's some code that you expect to be on the device, | |
that might be shared between applets. | |
</p> | |
<p> | |
Extended Applet and Library projects use the extended API in Java Card 3.0—so you can use java.lang.String | |
and so forth. The boot classpath will be different for Classic and Extended projects, so, for example, code completion will not show | |
java.lang.String in Classic projects, but will in Extended projects. | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/create-applet-app.png" alt="Creating a Java Card Applet Project" width="600"> </p> | |
<p> | |
Web Application projects are probably the coolest feature of Java Card 3.0. You get a skeleton project with a Servlet | |
implemented, and you have access to the full Servlet API. This is vastly easier to work with than either of the Applet-style application | |
types—you don't need any special code on the client to interact with an application running on a device, just a web browser! You can test your | |
applications locally using the Reference Implementation and your desktop web browser. | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/create-web-app.png" alt="Creating a Java Card Web Application Project" width="600"> </p> | |
<h2><a name="projects"></a>Working With a Project</h2> | |
<p>For this tutorial we create a new Web Project.</p> | |
<p> In the new web project Enter "Card Web Application" as project name and set the project location | |
to your NetBeansProjects directory. | |
Click Finish and the project appears in the Project tab. | |
</p> | |
<p> | |
Right-click the project node in the Project tab and | |
choose Properties from the context menu. | |
In the Run section of the Project Properties window, | |
you can change the platform and device that a project deploys to. | |
Click Close to save your changes. | |
</p> | |
<p> | |
Working on a Java Card web application is just like working | |
on any other web application that you deploy to a servlet container. | |
Press the Run button in the toolbar to run the Hello World sample. | |
When running a Java Card web app, a web browser window will open, | |
showing the servlet's output: <tt>Hello from webapplication1.MyServlet</tt>. | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/editor.png" alt="Code Editing in a Java Card Web Application Project" width="600"> </p> | |
<p> | |
When you run applet-type projects, the NetBeans IDE | |
offers two useful interfaces: command-line output, and the Java Card console. | |
Use the console to interact with the applet: You can send data | |
in hexadecimal and read the replies. | |
</p> | |
<p> | |
Tip: The RI contains further sample projects that are ready | |
to be opened and run in the NetBeans IDE. | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/run-customizer.png" alt="Java Card Project Run Properties" width="600"> </p> | |
<h2><a name="special"></a>Using Special Plugin Features</h2> | |
<p> | |
Java Card involves two bits of arcana which you don't encounter in other Java platforms: | |
</p> | |
<dl> | |
<dt><strong>Application Identifiers (AID)</strong></dt> | |
<dd>These are unique | |
identifiers that look like //aid//720A75E082/0058AEFC20. The first part | |
of hexadecimals is a vendor ID (you get one from the | |
<a href="http://iso.org/">International Standards Organization (ISO)</a>); | |
the second part is a unique value you come up with. AIDs are used to | |
identify applet classes, Java packages (classic applet & classic | |
library projects only), and unique instances of applets (you can deploy | |
the same applet multiple times on one device — the instance AID is used | |
to select which applet to send information to). | |
</dd> | |
<dt><strong>APDU scripts</strong></dt> | |
<dd>These are scripts to send data to an applet. | |
It involves a somewhat sadistic amount of hand-typed hexadecimal; the | |
script needs to select a specific applet instance, and then send data | |
to it. You can also use the Java Card console in place of sending a pre-written script. | |
</dd> | |
</dl> | |
<p> | |
While these two things are somewhat complicated, the NetBeans plug-ins | |
do their best to abstract away the complexities of dealing with them, | |
as follows: | |
</p> | |
<ul> | |
<li> | |
<p> | |
When you create a project, reasonable values for Applet AID, | |
Classic Package AID, and one Instance AID are automatically generated. | |
</p> | |
</li><li> | |
<p> | |
When you select the Applets tab in the Project Properties dialog, | |
the project scans its classpath for all Java Card applet subclasses it | |
can find: | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/customize-applets-pre.png" alt="Finding Applet Subclasses in a Java Card project" width="600"></p> | |
</li><li> | |
<p> | |
Once it has found them, the dialog allows you to select what | |
applets are actually deployed, and customize the AID values used, | |
deployment parameters and so forth. The IDE validates all of the data | |
you entered, so that it is hard to enter invalid data: | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/customize-applets.png" alt="Customizing Applet Deployment in a Java Card Project" width="600"> </p> | |
</li><li> | |
<p> | |
If you want to deploy two instances of the same applet, you can set | |
that up as well; however, for simple cases where you just want to | |
deploy one applet instance, you don't need to think about it: | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/customize-instances.png" alt="Customizing Deployed Applet Instances for a NetBeans Java Card Project" width="600"></p> | |
</li><li> | |
<p> | |
For testing running applets, you do not need to hand-write an | |
entire APDU script—you can use the built-in Console to interact with | |
deployed applets directly: | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/open-console.png" alt="Opening the APDU Console"></p> | |
<p> <img src="../../../images_www/articles/74/javacard/shell.png" alt="The APDU Console"> </p> | |
</li><li> | |
<p> | |
The "package AID" for Classic projects (they are only allowed to | |
contain one Java package) is also taken care of by the IDE, but is | |
customizable. | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/create-project-package-aid.png" alt="Customize Classic Package AID" width="600"> </p> | |
</li><li> | |
<p> | |
Part of all AID values in your projects will be an | |
ISO-assigned vendor ID (called the RID). For quickly getting started, | |
the IDE will generate a random value for the RID, which is fine for | |
development and testing. If you have an offical RID, you can enter that | |
in Tools > Options and it will be used for all new projects. | |
Click the Generate button in the Project Properties to update the | |
values in existing projects. | |
</p> | |
<p><img src="../../../images_www/articles/74/javacard/global-rid.png" alt="Set up the Global RID used by all AIDs for Java Card Projects" width="600"></p> | |
</li> | |
</ul> | |
<h2><a name="sdk"></a>Integrating Third-Party SDKs</h2> | |
<p> | |
Currently the tools only support the Java Card 3.0.2 Reference | |
Implementation, but they have an extensible API for integrating vendor cards. | |
The platform and device definitions are simply Properties files | |
which are imported by the build script. | |
</p> | |
<p> | |
Deployment is done through a set of Ant tasks provided by the card vendor. | |
This means that the projects created can be run outside the IDE, there is no lock-in. | |
The sources for the Ant tasks that are part of the Java Card RI can be downloaded from the | |
<a href="http://kenai.com/projects/javacard">Java Card project portal</a>, | |
along with NetBeans-ready sample projects. | |
</p> | |
<p> | |
Are you a card vendor who has created Java Card deployment tools? | |
Contact plugin author <a href="mailto:tboudreau@sun.com">Tim Boudreau</a> for details on | |
<a href="http://wiki.netbeans.org/JavaCardPlatformIntegration">how to integrate your card</a>! | |
Integration can be done at several levels, depending on how much support you wish to provide within the IDE for your card. | |
</p> | |
<div class="feedback-box"><a href="/about/contact_form.html?to=6&subject=NetBeans%20Java%20Card%20Development%20Quick%20Start%20Guide">Send Feedback on This Tutorial</a></div> | |
<br style="clear:both;" /> | |
<h2><a name="related"></a>Related Links</h2> | |
<ul> | |
<li> A lot of the credit for these modules goes to <a href="http://blogs.oracle.com/javacard/">Anki Nelaturu</a> | |
and the rest of the Java Card team. </li> | |
<li><a href="http://java.sun.com/javacard">Sun's Official Java Card Portal</a> — news, development kits, reference, specifications, FAQ. </li> | |
<li><a href="http://kenai.com/projects/javacard/pages/Home">Java Card project portal</a> — sources, sample projects, forums, documentation. </li> | |
<li> <a href="http://wiki.netbeans.org/JavaCardPlatformIntegration">Platform Integration for Card vendors</a></li> | |
<li> <a href="http://java.sun.com/developer/technicalArticles/javacard/javacard-servlets/">Deploying Servlets on Smart Cards: | |
Portable Web Servers with Java Card 3.0</a></li> | |
</ul> | |
</body> | |
</html> |