Interface ObjectGrid

Les méthodes suivantes permettent d'interagir avec une instance ObjectGrid.

Création et initialisation

Pour connaître la procédure de création d'instance ObjectGrid, reportez-vous à la rubrique consacrée à l'interface ObjectGrid. IL existe deux méthodes distinctes pour créer une instance ObjectGrid : par programmation ou à l'aide de fichiers XML de configuration. Pour plus d'informations, voir Interface ObjectGridManager.

Méthodes get ou set et méthodes factory

Toutes les méthodes set doivent être appelées avant l'initialisation de l'instance ObjectGrid. Tout appel à une méthode set après celui de la méthode initialize donne une exception java.lang.IllegalStateException. Chacune des méthodes getSession de l'interface ObjectGrid appelle également la méthode initialize de manière implicite. Il faut donc appeler les méthodes set avant tout appel aux méthodes getSession. Seule exception à cette règle : la définition, l'ajout et la suppression d'objets ObjectGridEventListener. En effet, ces objets ont le droit d'être traités après la fin de l'initialisation.

L'interface ObjectGrid contient les principales méthodes suivantes.
Tableau 1. ObjectGrid (interface). Les principales méthodes de l'interface ObjectGrid.
Méthode Description

BackingMap defineMap(String name);

defineMap : méthode factory permettant de définir une mappe de sauvegarde portant un nom exclusif. Pour plus d'informations sur les mappes de sauvegarde, voir l'interface BackingMap.

BackingMap getMap(String name);

getMap : retourne une mappe de sauvegarde précédemment définie par l'appel à defineMap. Cette méthode permet de configurer la mappe de sauvegarde, si elle ne l'a pas déjà été via une configuration XML.

BackingMap createMap(String name);

createMap : crée une mappe de sauvegarde, sans la mettre en cache pour qu'elle soit utilisée par cet ObjectGrid. Cette méthode s'utilise avec la méthode setMaps(List) de l'interface ObjectGrid, laquelle méthode met en cache des mappes de sauvegarde pour qu'elles soient utilisées par cet ObjectGrid. Ces méthodes s'utilisent lorsqu'on configure un ObjectGrid avec la structure Spring.

void setMaps(List mapList);

setMaps : supprime toutes les mappes de sauvegarde qui ont été précédemment définies dans cet ObjectGrid et les remplace par la liste des mappes qui est fournie.

public Session getSession() throws ObjectGridException, TransactionCallbackException;

getSession : retourne un objet Session, qui fournit des fonctionnalités begin, commit, rollback pour une unité d'oeuvre. Pour plus d'informations sur les objets Session, voir l'interface Session.

Session getSession(CredentialGenerator cg);

getSession(CredentialGenerator cg) : obtient une session avec un objet CredentialGenerator. Cette méthode ne peut être appelée que par le client ObjectGrid dans un environnement client/serveur.

Session getSession(Subject subject);

getSession(Subject subject) : autorise, pour obtenir un objet Session, l'utilisation d'un objet Subject spécifique à la place de l'objet configuré dans l'ObjectGrid.

void initialize() throws ObjectGridException;

initialize : l'ObjectGrid est initialisé et utilisable de manière générale. Cette méthode est appelée de manière implicite lorsque la méthode getSession est appelée si l'ObjectGrid n'est pas à l'état initialisé.

void destroy();

destroy : la structure est désassemblée et est inutilisable après l'appel de cette méthode.

void setTxTimeout(int timeout);

setTxTimeout : cette méthode permet de fixer la durée en secondes pendant laquelle a le droit de s'effectuer une transaction, qui est démarrée par une session créée par cette instance ObjectGrid. Si une transaction n'est pas terminée une fois ce délai écoulé, la session qui a démarré la transaction est marquée comme "timed out". Du fait de ce marquage, la prochaine méthode ObjectMap à être invoquée par la session expirée donne lieu à une exception com.ibm.websphere.objectgrid.TransactionTimeoutException. La session est marquée comme "rollback only", ce qui provoque son annulation même si l'application appelle la méthode commit au lieu de la méthode rollback après l'interception par l'application de l'exception TransactionTimeoutException. Un délai d'expiration de 0 indique que la transaction dispose d'une durée illimitée pour s'effectuer. La transaction n'expire pas si une valeur de 0 est utilisée. Si cette méthode n'est pas appelée, toute session retournée par la méthode getSession de cette interface a par défaut une valeur de délai d'expiration de transaction égale à 0. Une application peut substituer sa propre valeur de délai d'expiration sur la base d'un objet Session en utilisant la méthode setTransactionTimeout de l'interface com.ibm.websphere.objectgrid.Session.

Vous pouvez également configurer ce délai d'expiration dans le fichier objectGrid.xml en cas de scénario réparti.

int getTxTimeout();

getTxTimeout : retourne la valeur en secondes du délai d'expiration des transactions. Cette méthode retourne la même valeur que celle qui est passée comme paramètre timeout dans la méthode setTxTimeout. Si la méthode setTxTimeout n'a pas été appelée, la méthode retourne 0 pour indiquer que la transaction dispose d'une durée illimitée pour s'exécuter.

public int getObjectGridType();

Retourne le type de l'ObjectGrid. La valeur retournée équivaut à l'une des constantes déclarées dans cette interface : LOCAL, SERVER ou CLIENT.

public void registerEntities(Class[] entities);

Permet d'enregistrer une ou plusieurs entités à partir des métadonnées de classe. L'enregistrement des entités est obligatoire avant l'initialisation de l'ObjectGrid pour lier une entité à une mappe de sauvegarde et à tous les index définis. Cette méthode peut être appelée plusieurs fois.

public void registerEntities(URL entityXML);

Permet d'enregistrer une ou plusieurs entités à partir d'un fichier XML d'entités. L'enregistrement des entités est obligatoire avant l'initialisation de l'ObjectGrid pour lier une entité à une mappe de sauvegarde et à tous les index définis. Cette méthode peut être appelée plusieurs fois.

void setQueryConfig(QueryConfig queryConfig);

Permet de définir l'objet QueryConfig pour cet ObjectGrid. Un objet QueryConfig fournit des configurations de requêtes pour l'exécution de requêtes sur des objets dans les mappes de cet ObjectGrid.

 

   

//Sécurité

void setSecurityEnabled()

setSecurityEnabled : active la sécurité. La sécurité est désactivée par défaut.

void setPermissionCheckPeriod(long period);

setPermissionCheckPeriod : cette méthode accepte un seul paramètre qui indique à quelle fréquence vérifier le droit d'accès utilisé par un client. Une valeur de 0 pour ce paramètre demande au mécanisme d'autorisation, qu'il s'agisse de l'autorisation JAAS ou d'une autorisation personnalisée, de vérifier si le sujet courant dispose bien des droits d'accès. Selon l'implémentation des autorisations, cette stratégie risque d'être la cause de problèmes de performances. Mais ce type d'autorisation est disponible si nécessaire. Par ailleurs, une valeur inférieure à 0 indique le nombre de millisecondes pendant lequel un ensemble de droits d'accès doit être placé en cache avant de retourner au mécanisme d'autorisation pour être réactualisé. Ce paramètre fournit de bien meilleures performances mais, si les droits d'accès dorsaux viennent à être modifiés pendant ce délai, l'ObjectGrid risque d'autoriser ou au contraire d'interdire l'accès même si le fournisseur dorsal de sécurité a été modifié.

void setAuthorizationMechanism(int authMechanism);

setAuthorizationMechanism : permet de définir le mécanisme d'autorisation. La valeur par défaut est SecurityConstants.JAAS_AUTHORIZATION.

   

setSubjectSource(SubjectSource ss);

setSubjectSource : permet de définir le plug-in SubjectSource. Ce plug-in permet d'obtenir un objet Subject qui représente le client ObjectGrid. Ce Subject est utilisé pour l'autorisation ObjectGrid. La méthode SubjectSource.getSubject est appelée par l'environnement d'exécution ObjectGrid lorsque la méthode ObjectGrid.getSession est utilisée pour obtenir une session et que la sécurité est activée. Ce plug-in est utile pour un client déjà authentifié : il permet d'extraire l'objet Subject authentifié et de le transmettre à l'instance ObjectGrid. Aucune autre authentification n'est nécessaire.

setSubjectValidation(SubjectValidation sv);

setSubjectValidation : permet de définir le plug-in SubjectValidation pour cette instance ObjectGrid. Ce plug-in permet de valider qu'un Subject javax.security.auth.Subject qui est transmis à l'ObjectGrid est un Subject valide qui n'a pas été falsifié. Une implémentation de ce plug-in nécessite la prise en charge du créateur d'objets Subject, car le créateur est le seul à savoir si l'objet Subject a été ou non falsifié. Mais il peut arriver qu'un créateur de Subject n'ait pas les moyens de savoir si le Subject a été falsifié. Dans ce cas, ce plug-in ne doit pas être utilisé.

void setObjectGridAuthorization(ObjectGridAuthorization ogAuthorization);

Permet de définir l'ObjectGridAuthorization pour cette instance ObjectGrid. Passer un null à cette méthode supprime d'un appel précédent à cette méthode un objet ObjectGridAuthorization précédemment défini et indique que cet <code>ObjectGrid</code> n'est associé à aucun objet ObjectGridAuthorization. Cette méthode ne doit être utilisée que lorsque la sécurité de l'ObjectGrid est activée. Si cette sécurité est désactivée, l'objet ObjectGridAuthorization qui est fourni ne sera pas utilisé. Un plug-in ObjectGridAuthorization permet d'autoriser l'accès à l'ObjectGrid et aux mappes.

Interface ObjectGrid : plug-in

L'interface ObjectGrid comporte plusieurs points optionnels de connexion de plug-in, qui étendent les possibilités d'interactions.

void addEventListener(ObjectGridEventListener cb);
void setEventListeners(List cbList);
void removeEventListener(ObjectGridEventListener cb);
void setTransactionCallback(TransactionCallback callback);
int reserveSlot(String);
// Plug-in de sécurité
void setSubjectValidation(SubjectValidation subjectValidation);
void setSubjectSource(SubjectSource source);
  • ObjectGridEventListener : une interface ObjectGridEventListener permet de recevoir des notifications lorsqu'il se produit des événements importants dans l'ObjectGrid : initialisation de l'ObjectGrid, début de transaction, fin de transaction et destruction d'un ObjectGrid. Pour pouvoir être à l'écoute de ces événements, vous devez créer une classe qui implémente l'interface ObjectGridEventListener, classe que vous ajouterez à l'ObjectGrid. Ces programmes d'écoute sont associés à chaque session. Pour plus d'informations, voir Interfaces Listener et Session.
  • TransactionCallback : une interface de programme d'écoute TransactionCallback autorise des événements transactionnels (begin, commit et rollback) à envoyer des signaux à cette interface. En général, une interface d'écoute TransactionCallback est utilisé avec un chargeur. Pour plus d'informations, voir Plug-in TransactionCallback et Loaders. Ces événements permettent alors de coordonner les transactions avec une ressource externe ou au sein de plusieurs chargeurs.
  • reserveSlot : autorise les plug-in de cet ObjectGrid à réserver des emplacements utilisables dans les instances d'objets qui, comme TxID, disposent d'emplacements.
  • SubjectValidation. Si la sécurité est activée, ce plug-in permet de valider une classe javax.security.auth.Subject qui est transmise à l'ObjectGrid.
  • SubjectSource. Si la sécurité est activée, ce plug-in permet d'obtenir un objet Subject qui représente le client ObjectGrid. Ce Subject est alors utilisé pour l'autorisation ObjectGrid.

Pour plus d'informations sur les plug-in, voir la Présentation des plug-in.