Java Doc for JavaCardRMIConnection.java in  » 6.0-JDK-Modules » j2me » javax » microedition » jcrmi » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » 6.0 JDK Modules » j2me » javax.microedition.jcrmi 
Source Cross Reference  Class Diagram Java Document (Java Doc) 


javax.microedition.jcrmi.JavaCardRMIConnection

All known Subclasses:   com.sun.io.j2me.jcrmi.Protocol,  com.sun.midp.io.j2me.jcrmi.Protocol,
JavaCardRMIConnection
public interface JavaCardRMIConnection extends Connection(Code)
This interface defines the Java Card RMI connection which can be used by J2ME applications to communicate with applications on a smart card using Java Card RMI protocol.

Creating a Java Card RMI Connection

Java Card RMI connection is created by passing a generic connection URI string with a card application identifier (AID) and optionally the slot in which the card is inserted, to the javax.microedition.io.Connector.open Connector.open method. For example, the connection string:

 jcrmi:0;AID=A0.0.0.67.4.7.1F.3.2C.3
 
indicates that the connection is to be established with an application having the AID A0.0.0.67.4.7.1F.3.2C.3 and which resides in the smart card inserted in the default slot; that is, slot number 0. If the slot number is not specified, then the default slot is assumed.

Each Java Card RMI connection has a logical channel reserved exclusively for it. That is, the channel is dedicated to the J2ME application and the selected smart card application until the connection is closed. A smart card supporting logical channels allows the host device to open multiple logical channels to communicate with on-card applications. Logical channel other than the basic channel must be closed when corresponding connection is closed. Basic channel or channel 0 must remain open while the card is powered on.

Since the basic channel or channel 0 cannot be closed, the implementation should maintain its availability status. When a J2ME application asks for a new connection, the implementation would find out if channel 0 is in use by any application (native or J2ME application). If channel 0 is not in use, the implementation would acquire the channel 0 for communicating with the card application by setting the state of channel 0 to "IN USE". It would then select the desired application on channel 0. If the selection is successful, the newly created connection object would be returned to the J2ME application which can then use it to communicate with the card application. If the card application selection fails or the J2ME application calls close on the connection object, the availability state of the basic channel will be set back to "AVAILABLE" meaning that the basic channel is available for use.

When a J2ME application requests a connection to the card and channel 0 is in use by some other application (native or J2ME application), the implementation sends a MANAGE CHANNEL command to the card requesting a logical channel for the new connection. If there is a logical channel available, the card returns with the logical channel number which will be used by the new connection. The implementation would select the desired application on the newly allocated logical channel. If the selection is successful, the implementation returns the newly created connection object to the J2ME application which can then use it for communicating with the card application. If application selection fails or the J2ME application calls close() method to close the connection with the card application, the implementation will send a MANAGE CHANNEL command to the card to close the channel. The channel will then be available for use by other applications.

In the case when there are no logical channels available or the card does not support logical channels, the card will return an error. An IOException will be thrown and no connection object will be returned to the J2ME application.

Invoking Methods on Remote Objects in Java Card

Once the Java Card RMI connection is created, the J2ME application can obtain an initial remote reference object using JavaCardRMIConnection.getInitialReference() getInitialReference . Using this reference, the application can invoke methods of an initial remote object on the card and obtain other references to remote objects.

Communicating With Multiple Smart Card Applications

A J2ME application may connect and communicate with multiple smart card applications interchangeably. To achieve this the J2ME application can repeat the procedure mentioned above to create corresponding connection objects.

Closing a JavaCardRMIConnection

A J2ME application can call javax.microedition.io.Connection.close() on the connection object to terminate the connection and release the logical channel. The logical channel is free to be used by other applications. If an application terminates without closing an open connection, the implementation SHOULD perform the close operation automatically.

Exceptions that can be Thrown During Connection Establishment

If the card slot does not exist, or if the card is not inserted or powered on, or if application selection is failed a ConnectionNotFoundException must be thrown.

If the J2ME application is not allowed to access the application with the specified application identifier a SecurityException is thrown.

If there is no logical channel available to establish a connection, an IOException must be thrown.

If initial remote reference object can not be created a RemoteException must be thrown.

If a card is removed after the connection is established and then re-inserted, the J2ME application must re-establish the connection and get a new connection object. Any attempts to invoke remote method using the connection object created before removal of the card will result in RemoteException being thrown.

BNF Format for Connector.open() string

The URI MUST conform to the BNF syntax specified below. If the URI does not conform to this syntax, an IllegalArgumentException is thrown.

<JCRMI_connection_string> ::= "jcrmi:"< cardApplicationAddress>
<cardApplicationAddress> ::= [slot];<AID_string>
<slot> ::= smart card slot. (optional. Hexadecimal number identifying the smart card slot. Default slot assumed if left empty)
<AID_string> ::= "AID="<AID>
<AID> ::= <5 - 16 bytes>
An AID (Application Identifier) uniquely identifies a smart card application. It is represented by 5 to 16 hexadecimal bytes where each byte value is seperated by a ".".

Smart Card Slot Discovery Mechanism

J2ME devices may support a variable number of security elements (usually smart card slots). Some security elements are permanently attached to the device (e.g. a soldered chip), others are removable. The removable security elements may be cold-swappable, requiring the battery to be removed before the security element can be exchanged (e.g. a MiniSIM slot hidden behind the battery). Other removable security elements can be inserted and removed while the system is running. (e.g. a hot-swappable smart card reader).

A system property is defined to indicate the names of the smart card slots. The property can be queried through the System.getProperty() method using the key microedition.smartcardslots. The value returned is a comma-separated list of the smart card slots which can be used in the Connector.open() string to identify the specific smart card slot.

If the platform includes a (U)SIM card, it MUST be in slot 0.

The logical slot names include the slot number and a descriptor indicating the type of the slot. For cold-swappable slots the letter 'C' is appended to the slot number. For hot-swappable slots the letter 'H' is appended to the slot number. The slot descriptors (the letter 'C' and 'H' appended to the slot number) cannot be passed as part of the URI to open a connection to the smart card application. The J2ME application MUST remove the descriptor from the logical slot name and only use the slot number in URI to identify the specific smart card slot.

A typical configuration for a cold-swappable SIM card and a hot-swappable removable card would be:

 
microedition.smartcardslots: 0C,1H

Example

The following example shows how a JavaCardRMIConnection can be used to access a smart card application.

 try {
 JavaCardRMIConnection connection = (JavaCardRMIConnection)
 Connector.open("jcrmi:0;AID=A0.0.0.67.4.7.1F.3.2C.3");
 Counter counter = (Counter) connection.getInitialReference();
 ...
 currentValue = counter.add(50);
 ...
 connection.close();
 } catch (Exception e) {
 ...
 }
 

Note regarding PIN-related methods

A platform should implement the PIN entry UI in such a way that:

  • the UI is distinguishable from a UI generated by external sources (for example J2ME applications)
  • external sources are not able to retrieve or insert PIN data
  • If the static access control mechanism is implemented, the PIN related methods MUST be implemented as specified in the static access control mechanism. For further details see Appendix A (Recommended Security Element Access Control).



Field Summary
final public static  shortPINENTRY_CANCELLED
     This status is returned to the calling J2ME application if the operation for PIN verification/change/disable/ enable/unblock was not successful because the user cancelled the PIN entry request.


Method Summary
 shortchangePin(int pinID)
     A call to changePin method pops up a UI that requests the user for an old or existing PIN value and the new PIN value to change the value of the PIN.
 shortdisablePin(int pinID)
     A call to disablePin method pops up a UI that requests the user to enter the value for the PIN that is to be disabled.
 shortenablePin(int pinID)
     A call to enablePin method pops up a UI that requests the user to enter the value for the PIN that is to be enabled.
 shortenterPin(int pinID)
     A call to enterPin method pops up a UI that requests the PIN from the user.
 java.rmi.RemotegetInitialReference()
     Returns the stub object for an initial remote reference.
 shortunblockPin(int blockedPinID, int unblockingPinID)
     This is a high-level method that lets the J2ME application ask the user to enter the value for an unblocking PIN, and the new value for the blocked PIN and send these to the card.

Field Detail
PINENTRY_CANCELLED
final public static short PINENTRY_CANCELLED(Code)
This status is returned to the calling J2ME application if the operation for PIN verification/change/disable/ enable/unblock was not successful because the user cancelled the PIN entry request.





Method Detail
changePin
short changePin(int pinID) throws java.rmi.RemoteException(Code)
A call to changePin method pops up a UI that requests the user for an old or existing PIN value and the new PIN value to change the value of the PIN. The pinID field indicates which PIN is to be changed. The user can either cancel the request or continue. If the user enters the PIN values and chooses to continue the implementation is responsible for presenting the old and new values of the PIN to the card. If padding is required for the PIN, the implementation is responsible for providing appropriate padding.
Parameters:
  pinID - the type of PIN the implementation is suppose to promptthe user to change. PINENTRY_CANCELLED if the user cancelled the PIN entryrequest or the value returned by the remote method.
exception:
  java.rmi.RemoteException - is thrown if the PIN couldnot be communicated to the card or an exception is thrownby the card in response to the PIN entry.
exception:
  SecurityException - is thrown if the J2ME application doesnot have appropriate rights to ask for changing the PIN value.
exception:
  UnsupportedOperationException - is thrown if the implementation does not support this method.



disablePin
short disablePin(int pinID) throws java.rmi.RemoteException(Code)
A call to disablePin method pops up a UI that requests the user to enter the value for the PIN that is to be disabled. The pinID field indicates which PIN is to be disabled. The user can either cancel the request or continue. If the user enters the PIN and chooses to continue the implementation is responsible for presenting the PIN value to the card to disable PIN. If padding is required for the PIN, the implementation is responsible for providing appropriate padding.
Parameters:
  pinID - the type of PIN the implementation is required to promptthe user to enter. PINENTRY_CANCELLED if the user cancelled the PIN entryrequest or the value returned by the remote method.
exception:
  java.rmi.RemoteException - is thrown if the PIN couldnot be communicated to the card or an exception is thrownby the card in response to the PIN entry.
exception:
  SecurityException - is thrown if the J2ME application doesnot have appropriate rights to ask for disabling the PIN.
exception:
  UnsupportedOperationException - is thrown if the implementation does not support this method.



enablePin
short enablePin(int pinID) throws java.rmi.RemoteException(Code)
A call to enablePin method pops up a UI that requests the user to enter the value for the PIN that is to be enabled. The pinID field indicates which PIN is to be enabled. The user can either cancel the request or continue. If the user enters the PIN and chooses to continue the implementation is responsible for presenting the PIN value to the card for enabling the PIN. If padding is required for the PIN, the implementation is responsible for providing appropriate padding.
Parameters:
  pinID - the type of PIN the implementation is required to promptthe user to enter. PINENTRY_CANCELLED if the user cancelled the PIN entryrequest or the value returned by the remote method.
exception:
  java.rmi.RemoteException - is thrown if the PIN couldnot be communicated to the card or an exception is thrownby the card in response to the PIN entry.
exception:
  SecurityException - is thrown if the J2ME application doesnot have appropriate rights to ask for enabling the PIN.
exception:
  UnsupportedOperationException - is thrown if the implementation does not support this method.



enterPin
short enterPin(int pinID) throws java.rmi.RemoteException(Code)
A call to enterPin method pops up a UI that requests the PIN from the user. The pinID field indicates which PIN must be requested from the user. The user can either cancel the request or continue. If the user enters the PIN and chooses to continue, The implementation is responsible for presenting the PIN entered by the user to the card for verification. If padding is required for the PIN, the implementation is responsible for providing appropriate padding.
Parameters:
  pinID - the type of PIN the implementation is suppose to promptthe user to enter. PINENTRY_CANCELLED if the user cancelled the PIN entryrequest or the value returned by the remote method.
exception:
  java.rmi.RemoteException - is thrown if the PIN couldnot be communicated to the card or an exception is thrownby the card in response to the PIN entry.
exception:
  SecurityException - is thrown if the J2ME application doesnot have appropriate rights to ask for PIN verification.
exception:
  UnsupportedOperationException - is thrown if the implementation does not support this method.



getInitialReference
java.rmi.Remote getInitialReference()(Code)
Returns the stub object for an initial remote reference. the initial remote reference



unblockPin
short unblockPin(int blockedPinID, int unblockingPinID) throws java.rmi.RemoteException(Code)
This is a high-level method that lets the J2ME application ask the user to enter the value for an unblocking PIN, and the new value for the blocked PIN and send these to the card. A call to unblockPin method pops up a UI that requests the user to enter the value for the unblocking PIN and the new value for the blocked PIN. The unblockingPinID field indicates which unblocking PIN is to be used to unblock the blocked PIN which is indicated by the field blockedPinID. The user can either cancel the request or continue. If the user enters the PIN values and chooses to continue, the implementation is responsible for presenting the PIN values to the card for unblocking the blocked PIN. If padding is required for either of the PIN values, the implementation is responsible for providing appropriate padding.
Parameters:
  blockedPinID - the ID of PIN that is to be unblocked.
Parameters:
  unblockingPinID - the ID of unblocking PIN. PINENTRY_CANCELLED if the user cancelled the PIN entryrequest or the value returned by the remote method.
exception:
  java.rmi.RemoteException - is thrown if the PIN couldnot be communicated to the card or an exception is thrownby the card in response to the PIN entry.
exception:
  SecurityException - is thrown if the J2ME application doesnot have appropriate rights to ask for unblocking the PIN.
exception:
  UnsupportedOperationException - is thrown if the implementation does not support this method.



www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.