OpenCard  
 
OCF, the OpenCard Framework is a standard Java framework for working with Smart Cards.  
 

opencard.opt.database
Class BasicDatabase

java.lang.Object
  |
  +--opencard.core.service.CardService
        |
        +--opencard.opt.database.BasicDatabase
public class BasicDatabase
extends CardService
implements DatabaseCardService, DatabaseCardService.Constants

This class is designed as a basic default class which allows programmers to access ISO 7816-7-compliant smartcards.

It provides all methods necessary to access database smartcards, as describes in the ISO 7816-7 norm.

It is intended that the CardService developers for specific card use this class as a base class and by inheriting its functionalities

Since:
OCF1.2
Version:
$Id: BasicDatabase.java,v 1.1 1999/12/06 15:46:04 damke Exp $
See Also:
DatabaseCardService

Field Summary
protected  int MAX_SIZE
          MAX_SIZE represents maximum size of a command APDU that can be built.
 
Constructor Summary
BasicDatabase()
          Constructor called when creating a new BasicDatabase.
 
Method Summary
 void begin()
          Allocates space for a memory image, e.g. a row.
The memory space which is provided is implementation dependent.
 void commit()
          Validates all the modifications made since the transaction operation BEGIN as been executed.
The transaction operation BEGIN must have been previously performed.
 void createDictionary(java.lang.String dictionary)
          Defines a view on the system tables *O, *U and *P.
 void createTable(java.lang.String tableName, java.lang.String columnsList, byte maxNumberOfRows, SecurityAttribute securityAttribute)
          Defines a table with its columns and possibly with security attributes.
 void createTable(java.lang.String tableName, java.lang.String columnsList, SecurityAttribute securityAttribute)
           
 void createUser(java.lang.String userID, java.lang.String userProfile, SecurityAttribute securityAttribute)
          Initiates the registration of a user.
 void createView(java.lang.String viewName, java.lang.String tableName, java.lang.String colunmNames, java.lang.String conditions, SecurityAttribute securityAttribute)
          Defines a view on a table.
 void declareCursor(java.lang.String objectName, java.lang.String columnsName, java.lang.String conditions)
          Cursor is used for pointing to a row on a table, view or dictionary.
 void delete()
          Deletes a row in a table to which the cursor points.
 void deleteUser(java.lang.String userID)
          Allows a user to be deleted.
 void dropTable(java.lang.String tableName)
          Allows to drop a table.
A table can only be dropped by its owner.
 void dropView(java.lang.String viewName)
          Allows to drop a view.
A table can only be dropped by its owner.
 java.lang.String[] fetch()
          Allows to fetch a row or part of it.
 java.lang.String[] fetch(byte maxLength)
          Allows to fetch a row or part of it.
 java.lang.String[] fetchNext()
          Used for reading the logical next row from the cursor position.
 java.lang.String[] fetchNext(byte maxLength)
          Used for reading the logical next row from the cursor position.
 void grant(java.lang.String privileges, java.lang.String objectName, java.lang.String userID)
          Allows to grant privileges to a single user, to a user group or to all users.
The following rivileges may be granted.

Privileges for table access :
SELECT
INSERT
UPDATE
DELETE
ALL

Privileges for view access :
SELECT
UPDATE

Privileges for dictionary access :
SELECT
protected  void initialize(CardServiceScheduler scheduler, SmartCard smartcard, boolean blocking)
          Allows to initialize the cardservice.
 void insert(java.lang.String tableName, java.lang.String values)
          Used to insert a row in a table.
static boolean knows(CardID cid, CardServiceScheduler sched)
          A static method to analyze a smartcard in order to determine if it is an SCQL card, i.e., compliant with the ISO7816-7 standard.
 void next()
          Sets the current cursor on the next row satisfying the cursor specification.
A cursor must have been opened before.
 void open()
          Opens a cursor, i.e., the cursor is positioned on the first row which satisfies the selection previously defined with the declareCursor method.
 void presentUser(java.lang.String userID)
           
 void presentUser(java.lang.String userID, SecurityAttribute securityAttribute)
          Checks the presented user id.
 void revoke(java.lang.String privileges, java.lang.String objectName, java.lang.String userID)
          Allows to revoke privileges granted before.
Only the owner of the table or view can revoke privileges.
 void rollback()
          Restores the context in the way it was before the transaction operation BEGIN as been executed.
The transaction operation BEGIN must have been previously performed.
protected  ResponseAPDU sendAPDU(CommandAPDU cmd)
          This method is used to send APDU commands to the smartcard.
protected  void throwException(ResponseAPDU apdu)
          This method is used in this package to manage exceptions.
 void update(java.lang.String values)
          Updates one or more fields of a row in a table or view to which the cursor points.
The command can only be executed by the table owner or a user with the UPDATE privilege.
A cursor must be opened before.
The value for the special column USER, if present, is inserted by the card.
 
Methods inherited from class opencard.core.service.CardService
allocateCardChannel, getCard, getCardChannel, getCHVDialog, releaseCardChannel, setCardChannel, setCHVDialog
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_SIZE

protected final int MAX_SIZE
MAX_SIZE represents maximum size of a command APDU that can be built.
Constructor Detail

BasicDatabase

public BasicDatabase()
Constructor called when creating a new BasicDatabase.
Method Detail

initialize

protected void initialize(CardServiceScheduler scheduler,
                          SmartCard smartcard,
                          boolean blocking)
                   throws CardServiceException
Allows to initialize the cardservice. This method is called when instanciating the cardservice (after the call of the BasicDatabase constructor).
Parameters:
scheduler - The CardServiceScheduler.
smartcard - The SmartCard.
blocking - Boolean that defines if the smartcard blocks access for other applications while working or not.
Overrides:
initialize in class CardService
See Also:
BasicDatabase()

createTable

public void createTable(java.lang.String tableName,
                        java.lang.String columnsList,
                        byte maxNumberOfRows,
                        SecurityAttribute securityAttribute)
                 throws SCQLException
Defines a table with its columns and possibly with security attributes. The table definition is added in the object descriprion table.

A table can only be created by users with the DB_O profile (DataBase Owner) or DBOO (DataBase Object Owner).

Specified by:
createTable in interface DatabaseCardService
Parameters:
tablename - The name of the table to be created.
columnslist - The list of the columns of the table. This parameter is a string. Each column is separated by a semi-column from the next.
maxnumberofrows - The maximum number of rows that can be inserted in the table.
securityattribute - The security attributes.
Throws:
opencard.opt.database.SCQLException#SCQLException() -  
opencard.opt.database.SCQLException#SCQLException(java.lang.String) -  
See Also:
(java.lang.String, java.lang.String, java.lang.String, java.lang.String, byte);, (java.lang.String)

createTable

public void createTable(java.lang.String tableName,
                        java.lang.String columnsList,
                        SecurityAttribute securityAttribute)
                 throws SCQLException

createView

public void createView(java.lang.String viewName,
                       java.lang.String tableName,
                       java.lang.String colunmNames,
                       java.lang.String conditions,
                       SecurityAttribute securityAttribute)
                throws SCQLException
Defines a view on a table. The view definition is added to the object description table.
A view can only be created by the owner of the referenced table.
If several conditions are present, they are implicitely combinated with a logical AND.
Specified by:
createView in interface DatabaseCardService
Parameters:
viewname - The name of the view you want to create.
tablename - The name of the object on which you want to build your view.
colunmname - The list of fields presents in the view. Each field is separed from the next by a coma.
conditions - The list of conditions used to build the view. Each field is separed from the next by a coma.
securityattribute - The security attribute used to create the view.
Throws:
opencard.opt.database.SCQLException#SCQLException() -  
opencard.opt.database.SCQLException#SCQLException(java.lang.String) -  
See Also:
(java.lang.String, java.lang.String, byte, byte), (java.lang.String)

createDictionary

public void createDictionary(java.lang.String dictionary)
                      throws SCQLException
Defines a view on the system tables *O, *U and *P. The fixed view definitions are added by the card in the object descrition table.
A dictionary can only be created by the DB_O (DataBase Owner) or a DBOO (DataBase Object Owner).

Note : This command has no equivalence in SQL.
Specified by:
createDictionary in interface DatabaseCardService
Parameters:
dictionary - The name of the dictionary you want to create.
Throws:
opencard.opt.database.SCQLException#SCQLException() -  
opencard.opt.database.SCQLException#SCQLException(java.lang.String) -  
See Also:
opencard.opt.database.BasicDatabase#createTable(java.lang.String, java.lang.String ,byte, byte), (java.lang.String, java.lang.String, java.lang.String, java.lang.String)

dropTable

public void dropTable(java.lang.String tableName)
               throws SCQLException
Allows to drop a table.
A table can only be dropped by its owner. The privileges associated to the table should be automatically be dropped.
Specified by:
dropTable in interface DatabaseCardService
Parameters:
tablename - The name of the table you want to drop
Throws:
opencard.opt.database.SCQLException#SCQLException() -  
opencard.opt.database.SCQLException#SCQLException(java.lang.String) -  
See Also:
(java.lang.String)

dropView

public void dropView(java.lang.String viewName)
              throws SCQLException
Allows to drop a view.
A table can only be dropped by its owner. The privileges associated to the table should be automatically be dropped.
Specified by:
dropView in interface DatabaseCardService
Throws:
opencard.opt.database.SCQLException#SCQLException() -  
opencard.opt.database.SCQLException#SCQLException(java.lang.String) -  
See Also:
(java.lang.String)

grant

public void grant(java.lang.String privileges,
                  java.lang.String objectName,
                  java.lang.String userID)
           throws SCQLException
Allows to grant privileges to a single user, to a user group or to all users.

The following rivileges may be granted.

Privileges for table access :

  • SELECT
  • INSERT
  • UPDATE
  • DELETE
  • ALL

Privileges for view access :
  • SELECT
  • UPDATE

Privileges for dictionary access :
  • SELECT

Specified by:
grant in interface DatabaseCardService
Parameters:
privilege - The list of privileges to grant. Each privilege is a part of the string. Each privilege is separated from the next by a coma.
objectname - The object you want to grant (a table, a view or a dictionary).
userid - The user(s) you want to be granted privileges.
Throws:
opencard.opt.database.SCQLException#SCQLException() -  
opencard.opt.database.SCQLException#SCQLException(java.lang.String) -  
See Also:
(java.lang.String, java.lang.String, java.lang.String), opencard.opt.database.SecurityStatusNotSatisfiedException, IncorrectParameterInDataFieldException, OperationNotSupportedException, ReferencedObjectNotFoundException

revoke

public void revoke(java.lang.String privileges,
                   java.lang.String objectName,
                   java.lang.String userID)
            throws SCQLException
Allows to revoke privileges granted before.
Only the owner of the table or view can revoke privileges.
Specified by:
revoke in interface DatabaseCardService
Parameters:
privilege - The list of privileges to revoke. Each privilege is a part of the string. Each privilege is separated from the next by a coma.
objectname - The object you want to revoke privileges on (i.e., a table, a view or a dictionary).
userid - The user(s) you want to be revoked privileges.
Throws:
opencard.opt.database.SCQLException#SCQLException() -  
opencard.opt.database.SCQLException#SCQLException(java.lang.String) -  
See Also:
(java.lang.String, java.lang.String, java.lang.String), opencard.opt.database.SecurityStatusNotSatisfiedException, IncorrectParameterInDataFieldException, ReferencedObjectNotFoundException

declareCursor

public void declareCursor(java.lang.String objectName,
                          java.lang.String columnsName,
                          java.lang.String conditions)
                   throws SCQLException
Cursor is used for pointing to a row on a table, view or dictionary. This method is used for the declaration of a cursor.
The declaration of the cursor is only accepted if the actual user is authorized to access the referenced table, view or dictionary. The user has to be the owner of the referenced object or at least one privilege for access to the referenced object.
Only one cursor can exist at a given time, i.e., if a new cursor is declared then the previous is no longer valid.
Specified by:
declareCursor in interface DatabaseCardService
Parameters:
objectname - The name of the object on which you want to declare your cursor.
columnsname - The list of the columns you want to build your selection on.
condition - The string that contains the conditions to apply for the cursor.
See Also:
fetch(), fetch(byte), fetchNext(), fetchNext(byte), open(), next()

open

public void open()
          throws SCQLException
Opens a cursor, i.e., the cursor is positioned on the first row which satisfies the selection previously defined with the declareCursor method.
Specified by:
open in interface DatabaseCardService
See Also:
fetch(), fetch(byte), fetchNext(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), next()

next

public void next()
          throws SCQLException
Sets the current cursor on the next row satisfying the cursor specification.
A cursor must have been opened before.
Specified by:
next in interface DatabaseCardService
See Also:
fetch(), fetch(byte), fetchNext(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), open()

fetch

public java.lang.String[] fetch(byte maxLength)
                         throws SCQLException
Allows to fetch a row or part of it. The cursor has to point on the row to be fetched.
The operation can only be executed by the object owner or a user with the SELECT privilege A cursor must have been opened before.
Specified by:
fetch in interface DatabaseCardService
Parameters:
maxlength - The maximum length of expected data.
See Also:
fetch(), fetchNext(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), open(), opencard.opt.database.BasicDatabase#next(byte)

fetch

public java.lang.String[] fetch()
                         throws SCQLException
Allows to fetch a row or part of it. The cursor has to point on the row to be fetched.
The operation can only be executed by the object owner or a user with the SELECT privilege.
A cursor must have been opened before.
No maximum length of data is expected.
Specified by:
fetch in interface DatabaseCardService
See Also:
fetch(byte), fetchNext(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), open(), opencard.opt.database.BasicDatabase#next(byte)

fetchNext

public java.lang.String[] fetchNext(byte maxLength)
                             throws SCQLException
Used for reading the logical next row from the cursor position. The cursor is set to the row being fetched.
The operation can only be executed by the object owner or a user with the SELECT privilege.
A cursor must have been opened before.
Specified by:
fetchNext in interface DatabaseCardService
Parameters:
maxlength - The maximum length of expected data.
See Also:
fetch(byte), fetch(), fetchNext(), declareCursor(java.lang.String, java.lang.String, java.lang.String), open(), opencard.opt.database.BasicDatabase#next(byte)

fetchNext

public java.lang.String[] fetchNext()
                             throws SCQLException
Used for reading the logical next row from the cursor position. The cursor is set to the row fetched.
The operation can only be executed by the object owner or a user with the SELECT privilege. A cursor must have been opened before.
No maximum length of data is expected.
Specified by:
fetchNext in interface DatabaseCardService
See Also:
fetch(byte), fetch(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), open(), opencard.opt.database.BasicDatabase#next(byte)

insert

public void insert(java.lang.String tableName,
                   java.lang.String values)
            throws SCQLException
Used to insert a row in a table. A new row is always added at the end of a table. The cursor remains at its position.
The command can only be executed by the table owner or a user with the INSERT privilege.
The value for the special column USER, if present, is inserted by the card.
Specified by:
insert in interface DatabaseCardService
Parameters:
tablename - The name of the table you want to insert into.
values - The String that contains the list of values to be inserted.
See Also:
update(java.lang.String), delete()

update

public void update(java.lang.String values)
            throws SCQLException
Updates one or more fields of a row in a table or view to which the cursor points.
The command can only be executed by the table owner or a user with the UPDATE privilege.
A cursor must be opened before.
The value for the special column USER, if present, is inserted by the card.
Specified by:
update in interface DatabaseCardService
Parameters:
values - The String that contains the list of values to be updated.
See Also:
insert(java.lang.String, java.lang.String), delete()

delete

public void delete()
            throws SCQLException
Deletes a row in a table to which the cursor points. The cursor is moved to the logical next row.
The command can only be executed by the table owner or a user with the DELETE privilege for the referenced table.
Specified by:
delete in interface DatabaseCardService
See Also:
insert(java.lang.String, java.lang.String), update(java.lang.String)

begin

public void begin()
           throws SCQLException
Allocates space for a memory image, e.g. a row.
The memory space which is provided is implementation dependent. It is recommended that enough memory space for the buffering of at least one row is allocated.
Specified by:
begin in interface DatabaseCardService
See Also:
commit(), rollback()

commit

public void commit()
            throws SCQLException
Validates all the modifications made since the transaction operation BEGIN as been executed.
The transaction operation BEGIN must have been previously performed.
Specified by:
commit in interface DatabaseCardService
See Also:
begin(), rollback()

rollback

public void rollback()
              throws SCQLException
Restores the context in the way it was before the transaction operation BEGIN as been executed.
The transaction operation BEGIN must have been previously performed.
Specified by:
rollback in interface DatabaseCardService
See Also:
begin(), commit()

presentUser

public void presentUser(java.lang.String userID,
                        SecurityAttribute securityAttribute)
                 throws SCQLException
Checks the presented user id. If the user id is registred in the system table *U, the user characterized by its user id is set as current user.
There can only be one current user at a time per logical channel.
Specified by:
presentUser in interface DatabaseCardService
Parameters:
userid - the login name of the presented user id.
securityAttribute - the security attribute presented for authentication.
See Also:
opencard.opt.database.BasicDatabase#createUser(java.lang.String, java.lang.String, java.lang.String), deleteUser(java.lang.String), SecurityAttribute

presentUser

public void presentUser(java.lang.String userID)
                 throws SCQLException
Specified by:
presentUser in interface DatabaseCardService

createUser

public void createUser(java.lang.String userID,
                       java.lang.String userProfile,
                       SecurityAttribute securityAttribute)
                throws SCQLException
Initiates the registration of a user. In a SCQL environment a row in the user description table is inserted by the card.
This command can only be performed by users with profiles DB_O (i.e., DataBase Owner) or DBOO (i.e., DataBase Object Owner) with the right permissions. The user id has to be unique.
Specified by:
createUser in interface DatabaseCardService
Parameters:
userid - The login name of the presented user id.
userprofile - The profile of the presented user id.
securityAttribute - the security attribute presented for authentication.
See Also:
opencard.opt.database.BasicDatabase#presentUser(java.lang.String, java.lang.String), deleteUser(java.lang.String)

deleteUser

public void deleteUser(java.lang.String userID)
                throws SCQLException
Allows a user to be deleted. The respective row in the user description table is erased.
This operation can only be performed by the user owner. In order to ensure database integrity, privileges associated to this user should be automatically removed.
Specified by:
deleteUser in interface DatabaseCardService
Parameters:
userid - The login name of the presented user id.
See Also:
opencard.opt.database.BasicDatabase#presentUser(java.lang.String, java.lang.String), opencard.opt.database.BasicDatabase#createUser(java.lang.String, java.lang.String, java.lang.String)

throwException

protected void throwException(ResponseAPDU apdu)
                       throws SCQLException
This method is used in this package to manage exceptions. It analyzes the response sent back by the smartcard and raises the appropriate exception.
Parameters:
adpu - The responseAPDU to be analyzed.

sendAPDU

protected ResponseAPDU sendAPDU(CommandAPDU cmd)
                         throws SCQLException
This method is used to send APDU commands to the smartcard.
Parameters:
cmd - The APDU command to be sent.
Returns:
The APDU response send back by the smartcard.

knows

public static boolean knows(CardID cid,
                            CardServiceScheduler sched)
A static method to analyze a smartcard in order to determine if it is an SCQL card, i.e., compliant with the ISO7816-7 standard. It is not possible here to analyze only the card ATR because the standard does not specify anything about it. On the contrary the following method is applied:
  1. a temporary SlotChannel is allocated (using the scheduler),
  2. a 'PRESENT USER ("PUBLIC")' command w/o password is sent, and
  3. the response is analyzed (it should be 9000 for an SCQL card).

This method complies with the following OCF naming pattern:
"A CardService 'knows' how to recognize supported cards"
Parameters:
cid - the ATR of the smartcard
sched - a CardServiceScheduler for temporary communication
Returns:
true or false