Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Org.eclipse.higgins.icard"
(→Base ICard Interface) |
(→Base ICard Interface) |
||
Line 10: | Line 10: | ||
// Return the human friendly name of the card | // Return the human friendly name of the card | ||
String getDisplayName(); | String getDisplayName(); | ||
− | |||
− | |||
− | |||
// Return true if this card only manages information about a | // Return true if this card only manages information about a | ||
Line 25: | Line 22: | ||
// is what we believe the semantics that Microsoft intended and we currently | // is what we believe the semantics that Microsoft intended and we currently | ||
// see no reason not to follow | // see no reason not to follow | ||
− | // Return the identifier | + | // Return the identifier string |
String getCardID(); | String getCardID(); | ||
− | // Returns the human friendly name of the card issuer | + | // Returns the human friendly name of the card issuer |
String getIssuerName(); | String getIssuerName(); | ||
− | + | ||
− | // | + | // Returns the URI of the issuer |
− | + | String getIssuer(); | |
// Returns a background image of the card | // Returns a background image of the card | ||
Image getCardImage(); | Image getCardImage(); | ||
− | |||
− | |||
− | |||
// Return the mime type of the background image (JPEG or GIF) | // Return the mime type of the background image (JPEG or GIF) | ||
Line 50: | Line 44: | ||
Date getExpiredTime(); | Date getExpiredTime(); | ||
− | |||
− | |||
− | |||
− | |||
− | |||
// If card handles only simple claim types then | // If card handles only simple claim types then | ||
// return a list of all possible types of claims that are supported | // return a list of all possible types of claims that are supported | ||
// throw exception otherwise | // throw exception otherwise | ||
// This is here for backward compatibility with CardSpace cards | // This is here for backward compatibility with CardSpace cards | ||
− | List getSupportedSimpleClaimTypes(); | + | // |
+ | // Note: this is a convenience method that does the equivalent of | ||
+ | // c = getContext(); and then (presuming c has a simple schema) | ||
+ | // does creates a linear list of claim/attribute types from | ||
+ | // the schema of c (retrieved by c.getSchema()) | ||
+ | List getSupportedSimpleClaimTypes() throws ComplexSchemaException; | ||
− | // | + | // Returns a read-only Context whose Digital Subject(s) can be queried for |
− | // | + | // attribute values that are displayed in the card UI (e.g. the |
− | // | + | // I-Card Selector Service or I-Card Manager. |
− | + | // See also isSingle() retreive the CUID of the singleton Digital Subject | |
+ | // If a card does not support a display context it throws the | ||
+ | // NoDisplayContextException. In this case the user cannot see | ||
+ | // the values of the supported claim types, only the claim types | ||
+ | // themselves. | ||
+ | Context getDisplayContext() throws NoDisplayContextException; | ||
− | // Retrieve the value of a simple claim type | + | // Retrieve the value of a simple claim type (on a 'single' card) |
− | // Note: Implementations of this method will likely retrieve and cache all | + | // Note 1: Implementations of this method will likely retrieve and cache all |
// supported simple claim type values in a single operation | // supported simple claim type values in a single operation | ||
+ | // Note 2: This is a convenience method that performs a getContext() | ||
+ | // to get the context, finds the singleton DS, and reads the claimType | ||
+ | // attribute specified | ||
// Returns the value of the claim type ClaimType | // Returns the value of the claim type ClaimType | ||
− | String getClaimValue(String | + | String getClaimValue(String claimType) throws ComplexSchemaException; |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
// Return whether the user wishes to be asked for explicit release of | // Return whether the user wishes to be asked for explicit release of | ||
Line 87: | Line 80: | ||
// Set the release policy of this card | // Set the release policy of this card | ||
− | void setReleasePolicy(ReleasePolicy); | + | void setReleasePolicy(ReleasePolicy) throws CardNotOpenException; |
// Return a list of the types of expored card data stream formats supported | // Return a list of the types of expored card data stream formats supported | ||
Line 97: | Line 90: | ||
// E.g. CardSpace I-Cards will export CardSpace format data | // E.g. CardSpace I-Cards will export CardSpace format data | ||
String export(CardFormat format); | String export(CardFormat format); | ||
+ | |||
+ | // UPDATE-RELATED METHODS | ||
+ | |||
+ | // Open the card itself for update. These methods are | ||
+ | // used during the creation of a new self-issued card. | ||
+ | // Pass the URI of the agent that intends to update the card. | ||
+ | // If the editorID matches the issuerID of the card then | ||
+ | // update operations are allowed | ||
+ | // Throws CardNotOpenException if 'editorID' does not match the | ||
+ | // value of getIssuerURI() | ||
+ | void open(String editorID); | ||
+ | |||
+ | // Close a card for update. | ||
+ | void close() throws CardNotOpenException; | ||
+ | |||
+ | // Set the human friendly name of the card | ||
+ | // throws: CardUpdateException if card has not been opened | ||
+ | void setDisplayName(String name) throws CardNotOpenException; | ||
+ | |||
+ | // Sets the card's human friendly name of the card issuer | ||
+ | void setIssuerName(String name) throws CardNotOpenException; | ||
+ | |||
+ | // Sets the background image of the card | ||
+ | void setCardImage(Image image) throws CardNotOpenException; | ||
+ | |||
+ | // Set the expiration date and time | ||
+ | void setExpiredTime(Date date) throws CardNotOpenException; | ||
===To Do=== | ===To Do=== |
Revision as of 23:57, 8 December 2006
This page describes the one mandatory I-Card interface that all types of Higgins-compatible I-Cards must implement, as well as these optional interfaces:
- TokenCard
- URICard
Base ICard Interface
All I-Cards must implement the ICard Interface:
// Return the human friendly name of the card String getDisplayName(); // Return true if this card only manages information about a // exactly one Digital Subject boolean isSingle(); // Returns if 'isSingle()' is true, an optional contextually-unique identifier for the Digital Subject // Otherwise return null. String getCUID(); // A card identifier that is unique to the card issuer. Or at least that // is what we believe the semantics that Microsoft intended and we currently // see no reason not to follow // Return the identifier string String getCardID(); // Returns the human friendly name of the card issuer String getIssuerName();
// Returns the URI of the issuer String getIssuer(); // Returns a background image of the card Image getCardImage(); // Return the mime type of the background image (JPEG or GIF) String getImageMimeType(); // Returns when the card was first issued, created, orginated Date getTimeIssued(); // Returns (optionally) the time after which the card should // be considered expired, invalid. Otherwise returns null Date getExpiredTime(); // If card handles only simple claim types then // return a list of all possible types of claims that are supported // throw exception otherwise // This is here for backward compatibility with CardSpace cards // // Note: this is a convenience method that does the equivalent of // c = getContext(); and then (presuming c has a simple schema) // does creates a linear list of claim/attribute types from // the schema of c (retrieved by c.getSchema()) List getSupportedSimpleClaimTypes() throws ComplexSchemaException; // Returns a read-only Context whose Digital Subject(s) can be queried for // attribute values that are displayed in the card UI (e.g. the // I-Card Selector Service or I-Card Manager. // See also isSingle() retreive the CUID of the singleton Digital Subject // If a card does not support a display context it throws the // NoDisplayContextException. In this case the user cannot see // the values of the supported claim types, only the claim types // themselves. Context getDisplayContext() throws NoDisplayContextException; // Retrieve the value of a simple claim type (on a 'single' card) // Note 1: Implementations of this method will likely retrieve and cache all // supported simple claim type values in a single operation // Note 2: This is a convenience method that performs a getContext() // to get the context, finds the singleton DS, and reads the claimType // attribute specified // Returns the value of the claim type ClaimType String getClaimValue(String claimType) throws ComplexSchemaException; // Return whether the user wishes to be asked for explicit release of // this card's information (i) every time it is requested (ii) only // the first time it is requested (iii) never ReleasePolicy getReleasePolicy(); // Set the release policy of this card void setReleasePolicy(ReleasePolicy) throws CardNotOpenException; // Return a list of the types of expored card data stream formats supported // ?? presumably a CardFormat also mentions XML language and/or version number List getSupportedExportFormats(); // Return a data stream containing a serialization of the card // The format depends on the kind of card // E.g. CardSpace I-Cards will export CardSpace format data String export(CardFormat format);
// UPDATE-RELATED METHODS
// Open the card itself for update. These methods are // used during the creation of a new self-issued card. // Pass the URI of the agent that intends to update the card. // If the editorID matches the issuerID of the card then // update operations are allowed // Throws CardNotOpenException if 'editorID' does not match the // value of getIssuerURI() void open(String editorID);
// Close a card for update. void close() throws CardNotOpenException;
// Set the human friendly name of the card // throws: CardUpdateException if card has not been opened void setDisplayName(String name) throws CardNotOpenException;
// Sets the card's human friendly name of the card issuer void setIssuerName(String name) throws CardNotOpenException; // Sets the background image of the card void setCardImage(Image image) throws CardNotOpenException; // Set the expiration date and time void setExpiredTime(Date date) throws CardNotOpenException;
To Do
- Need methods to get/set the access control list idea (see I-Card)
TokenCard Interface
Some types of I-Cards may implement this interface.
// If card is of type (1) then return a Digital Identity // that satisfies the policy policy // The credential parameter used to authenticate to the // Token Issuer–-may be null if Token Issuer policy doesn’t require it DigitalIdentity requestDigitalIdentity(Policy policy, DigitalIdentity credential); // Return the EPR of the card issuer // For CardSpace cards this is either the local STS endpoint (for // self-asserted cards) or a remote STS (for managed cards) EndpointReference getCardIssuerEndpoint(); // Return a list of {endpoint references, credential hint, credential selector} List getTokenServices() // Return a list of supported token types List getSupportedTokenTypes(); // Is the RP identity required in the token request message? boolean getRequireAppliesTo() // Returns the issuer that is referenced in the returned RSTR (or null if no issuer is listed) String getIssuedTokenIssuer();
URICard Interface
Some types of I-Cards may implement this interface. The card object encapsulates a ContextRef URI (that may be an XRI) that refers to an identity attribute-providing service (usually a network endpoint).
The I-Card Providers developed as part of the Higgins project use the Identity Attribute Service to connect to the remote (or local) Context data referenced by this ContextRef
(Note: If ICard.isSingle() is true, then implementations can invoke ICard.getCUID() to retreive the CUID of the Digital Subject with the Context returned by .getContextRef() below.)
// Return a URI --the ContextRef String getContextRef();