< Zurück | Weiter >

Provider anfordern

Diese Lerneinheit des Lernprogramms veranschaulicht den ersten Schritt bei der Verwendung des Programmiermodells der ClearQuest CM-API, um mit Rational ClearQuest-Ressourcen zu arbeiten.
Bevor Sie Ressourcen in einem Produkt-Repository, beispielsweise in einer Rational ClearQuest-Benutzerdatenbank, abrufen, ändern, erstellen oder löschen können, müssen Sie zunächst eine Instanz eines Providerobjekts für diesen Typ des Produkt-Repositorys erstellen.

Das Provider-Objekt implementiert die Schnittstelle StpProvider und verbindet dadurch die anderen CM-API-Schnittstellen mit der von der CM-API-Bibliothek bereitgestellten Implementierung.

Die CqProvider-Implementierungsklasse wird durch die Literalzeichenfolge CqProvider.CQ_ONLY_PROVIDER_CLASS benannt. Übergeben Sie diese an die Methode ProviderFactory.createProvider, um eine Instanz der Klasse CqProvider der ClearQuest CM-API zu erhalten.

Die Methode ProviderFactory.createProvider benötigt außerdem ein Callback-Objekt (Rückrufobjekt) aus dem der instanziierte Provider Authentication-Objekte (Authentifizierungsobjekte) anfordern kann. Das Authentication-Objekt stellt dem Provider die Berechtigungsnachweise bereit, die zur Authentifizierung des Benutzers als Rational ClearQuest-Benutzer notwendig sind, bevor Operationen in einer Datenbank ausgeführt werden (beispielsweise die Statusänderung eines Datensatzes oder die Änderung von Feldwerten). Die Verwendung eines von Ihnen angegebenen Callback-Objekts ermöglicht Ihrer Anwendung die vollständige Kontrolle über die Anforderung von Benutzerberechtigungsnachweisen (Benutzername und Kennwort), die in der Anwendung explizit festgelegt werden können oder von dem Benutzer beim Start oder beim ersten Mal, wenn sie benötigt werden, angefordert werden können.

Da ein Provider-Objekt für alle Anwendungsfälle der Programmierung mit der ClearQuest CM-API erforderlich ist, wird in allen Beispielen in diesem Lernprogramm eine Methode getProvider verwendet, die in der Klasse Utilities definiert ist und von allen Anwendungen verwendet werden soll. Das Callback-Objekt, das ebenfalls in der Klasse Utilities (Dienstprogramme) definiert ist, fordert beim ersten Zugriff des Benutzers auf eine Datenbank den Benutzernamen und das Kennwort des Benutzers an, und verwendet diese Berechtigungsnachweise anschließend so lange sie gültig sind.

/**
 * Einfaches Authentication-Objekt, in dem Benutzername und Kennwort,
 * die vom Benutzer angegeben wurden, für die Verwendung durch die
 * ClearQuest CM-API zwischengespeichert werden.
 */
static class UnPw implements Authentication {
    /**
     * Erstellt ein Authentication-Objekt
     * 
     * @param unpw - ein String[] (Zeichenfolge) mit Benutzername und Kennwort
     */
    UnPw(String[] unpw) {  m_data = unpw; }

    public String loginName() { return m_data[0]; }
    public String password() { return m_data.length > 1 ? m_data[1] : ""; };

    /** Die zwischengespeicherten Berechtigungsnachweise */
    private String[] m_data;
}


/**
 * Erstellt eine Instanz eines CM-API-Providers für ClearQuest.
 * 
 * @return - das instanziierte CqProvider-Objekt
 * @throws Exception
 *             - wenn der Provider nicth instanziiert werden konnte
 */
static StpProvider getProvider() throws Exception {
    try {
        Callback callback = new StpCallback() {
            private UnPw m_unpw;

            public Authentication getAuthentication(String r, int c)
            {   return null; /* Will not be called */   }

            public Authentication getAuthenticationEx(Domain domain,
                                                      String realm,
                                                      int retryCount,
                                                      StpProvider provider,
                                                      WvcmException failure) 
            throws WvcmException
            {
                // Versuch, die letzten Berechtigungsnachweisee in jedem neuen Repository zu verwenden
                if (m_unpw != null && retryCount == 0)
                    return m_unpw;

                String title = "Enter " + domain 
                        + " Username '+' Password for "
                        + realm + " [" + retryCount + "]";
                
                if (failure != null)
                    title = "Login failed: " + failure + "\n" + title;
                
                String unpw = JOptionPane.showInputDialog(title, "admin+");

                if (unpw == null || unpw.length() == 0)
                    throw new IllegalAccessError("User canceled request");
                
                if (unpw.equals("anonymous"))
                    return null;
                
                if (unpw.startsWith("@")) {
                    File file = new File(unpw.substring(1));

                    try {
                        FileReader reader = new FileReader(file);
                        char[] buf = new char[100];
                        int count = reader.read(buf);

                        unpw = new String(buf, 0, count);
                        reader.close();
                    } catch (Throwable t) {
                        Utilities.exception(null,
                                            "Reading password file " + unpw,
                                            t);
                    }
                }

                return m_unpw = new UnPw(unpw.split("\\+", -2));
            }
        };

        // Provider-Instanz erstellen
        return (StpProvider) ProviderFactory
            .createProvider(StpProvider.PROVIDER_CLASS, callback);
    } catch (InvocationTargetException ite) {
        WvcmException e = (WvcmException) ite.getTargetException();

        System.out.println("*** " + e);
        
        for (Throwable nested: e.getNestedExceptions())
            System.out.println("***  " + nested);

        throw e;
    }
}

In diesem Beispiel wird eine Instanz der erweiterten Schnittstelle StpProvider.StpCallback verwendet, weil für diese Schnittstelle bei Anforderung der Authentifizierung mehr Informationen bereitgestellt werden.

Da die ClearQuest CM-API alle Fehler durch Auslösen der Ausnahme StpException meldet, wird in die Klasse Utilities eine Methode aufgenommen, die die Informationen in einer solchen Ausnahme als Textnachricht formatiert und in einem Swing-Dialog anzeigt.

/**
 * Extrahiert den Nachrichteninhalt aus einem Throwable-Objekt und gibt ihn als
 * hierarchischen Array von Strings zurück, wobei die Verschachtelung der
 * Nachrichtenkomponenten des Throwable-Objekts übernommen wird. * Diese Struktur kann in einen SWING-Aufruf des Typs
 * showMessageDialog formatiert werden.
  * 
 * @param ex - das Throwable-Objekt, dessen Nachrichteninhalt extrahiert werden soll
 * @return - Wenn das angegebene Throwable-Objekt verschachtelte Komponenten enthält,
 *           wird ein Array zurückgegeben, der die Nachricht des Throwable-Objekts
 *           enthält, und ein Array, der aus den verschachtelten Nachrichten besteht.
  */
private static Object messages(Throwable ex) {
    String msg = ex.getLocalizedMessage();

    if (msg == null || msg.length() == 0)
        msg = ex.toString();

    if (ex instanceof StpException) {
        Throwable[] nested = ((StpException) ex).getNestedExceptions();

        if (nested != null && nested.length > 0) {
            Object[] msgs = new Object[nested.length];

            for (int i = 0; i < msgs.length; ++i)
                msgs[i] = messages(nested[i]);

            return new Object[] { msg, msgs };
        }
    } else if (ex.getCause() != null) {
        return new Object[] {msg, new Object[]{messages(ex.getCause())}};
    }

    return msg;
}

/**
 * Zeigt einen Swing-Dialog mit den Nachrichten an, die einem bestimmten
 * Throwable-Objekt zugeordnet sind.
  * 
 * @param frame - der übergeordnete Frame für den Nachrichtendialog
 * @param title - der Titel, der im Dialogfenster angezeigt werden soll
 * @param ex - das Throwable-Objekt, dessen Nachrichteninhalt angezeigt werden soll
 */
static void exception(Component frame, String title, Throwable ex) {
    JOptionPane.showMessageDialog(frame,
                                    messages(ex),
                                    title,
                                    JOptionPane.ERROR_MESSAGE);
}
Sie verfügen jetzt über den Code zum Anfordern eines Providers und zum Behandeln von Ausnahmen. Sie können beginnen, mit Ressourcen zu arbeiten, die in einer Rational ClearQuest-Benutzerdatenbank verfügbar sind.

Prüfpunkt der Lerneinheit

Die ersten Schritte beim Schreiben von Programmen mit der ClearQuest CM-API sind das Erstellen eines Callback-Objekts und das Anfordern eines Provider-Objekts, aus dem heraus Sie mit produktspezifischen Ressourcen arbeiten können.
In dieser Lerneinheit haben Sie folgende Kenntnisse erworben:
  • Sie haben Kenntnisse über Callback-Objekte erworben.
  • Sie haben Kenntnisse über Provider-Objekte erworben.
  • Sie haben die Ausnahmebehandlung in der ClearQuest CM-API kennengelernt.
  • Sie haben gelernt, wie mit der ClearQuest CM-API Instanzen von Callback- und Provider-Objekten erstellt werden.
  • Sie haben gelernt, wie die ClearQuest CM-API für die Ausnahmebehandlung verwendet wird.
< Zurück | Weiter >

Feedback