| <!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> |