Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## opencard.opt.database
Class BasicDatabase

    java.lang.Object
      |
      +--opencard.core.service.CardService
            |
            +--opencard.opt.database.BasicDatabase

public class BasicDatabase
extends opencard.core.service.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
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(opencard.core.service.CardServiceScheduler scheduler, opencard.core.service.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(opencard.core.terminal.CardID cid, opencard.core.service.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 opencard.core.terminal.ResponseAPDU` | `sendAPDU(opencard.core.terminal.CommandAPDU cmd)` This method is used to send APDU commands to the smartcard.
`protected void` | `throwException(opencard.core.terminal.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(opencard.core.service.CardServiceScheduler scheduler,
                              opencard.core.service.SmartCard smartcard,
                              boolean blocking)
                       throws opencard.core.service.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 opencard.core.service.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(opencard.core.terminal.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 opencard.core.terminal.ResponseAPDU sendAPDU(opencard.core.terminal.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(opencard.core.terminal.CardID cid,
                                opencard.core.service.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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD