MobileFirst Foundation 8.0 Migrations-Cookbook

Maven-Adapter erfordern, dass auf der Entwicklerworkstation Apache Maven installiert ist.

1. Installieren Sie Apache Maven.
   • Laden Sie die Apache-Maven-ZIP-Datei herunter.
   • Fügen Sie eine Variable MVN_PATH hinzu, die auf den Maven-Ordner zeigt.
   • Mac und Linux:
     Bearbeiten Sie wie folgt Ihre Datei ~/.bash_profile:

     #### Apache-Maven-Beispielposition
     
     export MVN_PATH="/usr/local/bin"

   • Windows: Folgen Sie dieser Anleitung.
   • Überprüfen Sie die Installation, indem Sie mvn -v ausführen.
2. In diesem Cookbook wird die MobileFirst CLI verwendet, um Maven-Befehle für die Erstellung der Adapter aufzurufen.
   • Installieren Sie NodeJS als vorausgesetztes Produkt für das Tool, sofern dies noch nicht geschehen ist.
   • Führen Sie in einem Befehlszeilenfenster den Befehl npm install -g mfpdev-cli aus. (Sie können das Produkt auch über das Download-Center in der MobileFirst Operations Console herunterladen und installieren.)
   • Überprüfen Sie die Installation, indem Sie mfpdev -v ausführen.

Erstellen Sie eine neue Adaptervorlage, die zu Ihrem Adaptertyp, Ihrem Adapternamen und Ihrem Paketnamen passt.
Dadurch vereinfachen Sie die Migration, da die Adaptermetadaten ähnlich sind und so keine gesonderte Bearbeitung erfordern.

• Führen Sie in einem Befehlszeilenfenster den Befehl mfpdev adapter create aus.
• Wählen Sie den Adaptertyp (HTTP- bzw. SQL-JavaScript-Adapter oder Java-Adapter) aus.
• Geben Sie eine GroupID an.
• Wenn Sie einen Java-Adapter erstellen, müssen Sie den zuvor verwendeten Paketnamen angeben (z. B. "com.sample").

Legen Sie vor Ausführung des Migrationstools den Modus für die Migration fest. Es gibt zwei unterstützte Modi.

• migrate
  Im Modus migrate können Sie die Migration von Client-Apps und Adaptern zusammen mit der Servermigration auf Mobile Foundation Version 8.0 durchführen. 
• compatibility
  Im Modus compatibility ist nur eine Servermigration möglich. Für die Clientmigration wird das Mobile Foundation Migration Studio verwendet.

Führen Sie den folgenden Befehl aus, um den Migrationsmodus festzulegen.

Hinweis: Die Befehle scan und client können nicht ausgeführt werden, wenn der Modus auf compatibility gesetzt ist. Führen Sie das Unterstützungstool für die Migration mit der Option server aus und geben Sie das Stammverzeichnis Ihres älteren Worklight-Projekts an.

1. Führen Sie das Unterstützungstool für Migration wie folgt aus, um ein Worklight-Projekt der Version 7.1 auf Mobile Foundation Version 8.0 zu migrieren.
   mfpmigrate server --In /Users/WorklightProject**/ --Out /Users/Migrate80Project
   
   

   SYNTAX

   mfpmigrate server [--in|-i <Quellenverzeichnis>] [--out|-o <Zielverzeichnis>] [--projectName|-p <neues_Projektverzeichnis>]

   
   

   BESCHREIBUNG

   Das Tool führt eine Migration für sichere Realms und Adapter eines vorhandenen MobileFirst-Projekts durch.

   
   

   OPTIONEN

   <Quellenverzeichnis>: Das <Quellenverzeichnis> muss der Stammordner des zu migrierenden MobileFirst-Projekts sein. Dieser Parameter ist obligatorisch.

   <Zielverzeichnis>: Das <Zielverzeichnis> ist das Verzeichnis, das nach der Migration die Adapter enthalten soll.

   Das Migrationstool scannt die Adapter und Realms und führt die folgenden Schritte aus:

   1. Es erstellt eine Schablone für die Adapter und unterstützten Sicherheitsüberprüfungen.
   2. Es verschiebt die Adapterquellen in das neu erstellte Maven-Artefakt.
   3. Es aktualisiert das POM mit den Abhängigkeiten.
   4. Es erstellt einen zusammenfassenden Bericht über die ausgeführten Schritte und die Änderungen, die manuell vorgenommen werden müssen, um die Migration abzuschließen.

2. Für vorhandene Adapter und eine vorhandene Datei worklight.properties ermittelt das Tool alle nicht mehr verwendeten und nicht unterstützten APIs von Adaptern der Version 7.1 und führt die folgenden Schritte aus:

   1. Es ersetzt nicht mehr verwendete bzw. nicht unterstützte APIs durch geeignete APIs der Version 8.0.
   2. Es generiert Adapter der Version 8.0 für die entsprechenden Adapter der Version 7.1 an der angegebenen Ausgabeposition.
   3. Entwickler können zum Verzeichnis für migrierte Adapter navigieren und einen Maven-Befehl (mvn clean install  adapter:deploy) absetzen, um den Adapter zu erstellen und im Server von Mobile Foundation Version 8.0 zu implementieren.

      Hinweis: Mit der migrierten Adapterdatei pom.xml wir der Adapter im lokal ausgeführten Mobile Foundation Server implementiert. Falls die Implementierung in einer anderen Mobile-Foundation-Server-Instanz erfolgen soll, aktualisieren Sie die Serverdetails und Berechtigungsnachweise in pom.xml, bevor Sie den maven-Befehl absetzen.

   4. Die Datei worklight.properties wird gescannt, um herauszufinden, ob eine Eigenschaft explizit die Aufnahme eines JNDI-Wertes in den Server von Mobile Foundation Version 8.0 erfordert. Die entsprechenden Einträge werden im Bericht ausgegeben.

3. Das Tool identifiziert alle unterstützten und nicht mehr verwendeten Realms in der Datei AuthenticationConfig.xml und führt folgende Schritte aus:

   1. Es gibt im Ergebnisbericht eine Liste der in der Authentifizierungskonfiguration des Benutzers verwendeten Realms aus, die vorkonfiguriert und in Version 8,0 mit vordefinierten Sicherheitsüberprüfungen verfügbar sind. (Die Benutzer müssen keine weiteren Aktionen ausführen.)
   2. Es listet nicht unterstützte Realms auf. (In Mobile Foundation Version 8.0 ist für diese Realms keine Unterstützung verfügbar.)
   3. Für unterstützte Realms, die migriert werden müssen, führt das Tool die folgenden Schritte aus:
      1. Es identifiziert die am besten geeignete Sicherheitsüberprüfung (SecurityCheck) für die Migration eines bestimmten Realms.
      2. Es generiert eine SecurityCheck-Vorlage mit identifizierten SecurityCheck-Basisklassen. Als Name wird der Name des Realms mit dem Suffix SecurityCheck verwendet.
      3. Es identifiziert die Abfrage- und Validierungsmethoden im Realm und kopiert sie als integrierte Kommentare in die entsprechende SecurityCheck-Methode, sodass der Benutzer auf sie zurückgreifen und dieselbe Validierung in der neu generierten SecurityCheck-Vorlage implementieren kann.

         Sehen Sie sich die folgende Zuordnung an, damit Sie verstehen, in wie weit die in Realmmethoden implementierte Authentifizierungslogik für die generierte SecurityCheck-Vorlage passend ist.

         Adapterauthentifizierungsrealm

         Das Adapterauthentifzierungsrealm ist in der Datei AuthenticationConfig.xml definiert. Nachfolgend sehen Sie eine Beispieldefinition.

         
         <realm loginModule="SampleLoginModule" name="SampleRealm">
           <className>com.worklight.integration.auth.AdapterAuthenticator</className>
           <parameter name="login-function" value="SampleAdapter.onAuthTrigger"/>
           <parameter name="logout-function" value="SampleAdapter.onLogout"/>
         </realm>
         

         Die obige Konfiguration von Version 7.1 kann wie folgt einer Sicherheitsüberprüfung (ValidationCredentialsSecurityCheck) zugeordnet werden:

         ValidationCredentialsSecurityCheck.createChallenge	Diese Methode kann für die Implementierung einer Abfrage einen ähnlichen Ansatz wie in SampleAdapter.onAuthTrigger verwenden. Beachten Sie jedoch, dass während der Migration Schnittstellenänderungen berücksichtigt werden müssen.
         ValidationCredentialsSecurityCheck.validateCredentials	Es gibt keine mit der obigen Realmdefinition vergleichbare Zuordnung. Für diese Methode ist daher keine Zuordnung möglich. Es hat sich gezeigt, dass Kunden diese Methode in Version 7.1 in einer der Ressourcenadaptermethoden implementiert haben und bei Erfolg der Avfragemethode über den Abfragehandler (ChallengeHandler) der Anwendung diese Methode aufgerufen haben.

         Eine ähnliche Zuordnung wird für alle unterstützten Realms aus Version 7.1 entsprechend ihrer jeweiligen Definition vorgenommen, z. B. für das Realm Form Based Authenticator, das Realm Basic Authenticator und für Custom Authenticators.

         Realmtyo in Version 7.1	Methodendefinitionen im Realm	SecurityCheck-Methode in Mobile Foundation Version 8.0
         CustomAuthentication	createIdentity	<UserAuthenticationSecurityCheck> createUser
         	processRequest	createChallenge
         	CustomAuhenticator.processAuthenticationFailure CustomAuhenticator.changeResponse on success CustomLoginModule.login	validateCredentials
         	CustomLoginmodule.logout	Logout
         Form Based authenticator	CustomLoginModule.login	<UserAuthenticationSecurityCheck> validateCredentials
         	CustomLoginmodule.logout	Logout

4. Nutzen Sie den zusammenfassenden Bericht wie folgt:

   1. Verschaffen Sie sich einen Überblick über die Schritte des Unterstützungstools für die Migration.
   2. Ordnen Sie nicht unterstützte APIs unterstützten APIs zu, wenn eine direkte Migration nicht möglich ist.
   3. Stellen Sie fest, welche nicht unterstützten Adapter/Realms in Ihrem traditionellen Worklight-Projekt verwendet werden.
   4. Gewinnen Sie Einblicke in andere technische Herausforderungen oder Engpässe Ihres bestehenden Entwurfs und lesen Sie die folgenden Informationen zu neuen Entwicklungskonzepten für die Meisterung dieser Herausforderungen.

1. Navigieren Sie in Ihrem Dateisystem zum JavaScript-Adapterordner, z. B. zu ../Desktop/JavaScriptAdapters/adapters/RSSReader.
2. Öffnen Sie ein anderes Fenster und navigieren Sie zu Ihrem neuen Maven-Projekt, z. B. zu ../Desktop/MigratedAdapter, und zum Ordner src/main/adapter-resources.
3. Kopieren Sie die vorhandenen Adapterdateien in diesen Ordner.
4. Bearbeiten Sie die Datei adapter.xml. Ersetzen Sie den Inhalt der Datei durch den XML-Inhalt Ihres vorhandenen Adapters (in diesem Beispiel RSSReader.xml).
5. Bearbeiten Sie die Datei js/{adapter-name}-impl.js. Ersetzen Sie den Inhalt der Datei durch den Inhalt Ihres vorhandenen Adapters (in diesem Beispiel RSSReader-impl.js).

1. Navigieren Sie in Ihrem Dateisystem zum JavaScript-Adapterordner, z. B. zu ../Desktop/JavaScriptAdapters/adapters/SQLAdapter.
2. Öffnen Sie ein anderes Fenster und navigieren Sie zu Ihrem neuen Maven-Projekt, z. B. zu ../Desktop/MigratedAdapter, und zum Ordner src/main/adapter-resources.
3. Bearbeiten Sie die Datei adapter.xml. Ersetzen Sie den Inhalt der Datei durch den XML-Inhalt Ihres vorhandenen Adapters (in diesem Beispiel SQLAdapter.xml).
4. Bearbeiten Sie die Datei js/{adapter-name}-impl.js. Ersetzen Sie den Inhalt der Datei durch den Inhalt Ihres vorhandenen Adapters (in diesem Beispiel SQLAdapter-impl.js).

Hier kommen Maven-Abhängigkeiten ins Spiel. Da Worklight/MobileFirst Studio nicht verwendet wird, wo sich der Datenbankconnector im Ordner server/lib befand, müssen Sie den Connector durch eine Maven-Abhängigkeit ersetzen.

1. Gehen Sie zum neu erstellten Maven-Projekt zurück und öffnen Sie die Datei pom.xml auf der Ausgangsebene des Verzeichnisses.
2. Fügen Sie eine Abhängigkeit für Ihren Datenbanktyp hinzu. Sie können auf der Maven-Central-Website nach der entsprechenden Abhängigkeit suchen.
3. Verwenden Sie in diesem Beispiel die MySQL-Datenbank. Fügen Sie im Abschnitt dependencies den folgenden Codeblock hinzu:

   <dependency>
       <groupId>mysql</groupId>
       <artifactId>mysql-connector-java</artifactId>
       <version>5.1.6</version>
   </dependency>

Wenn es weitere Abhängigkeiten gibt, zeigen Sie in der Datei pom.xml auf diese Abhängigkeiten (d. h. auf eine lokale Datei oder auf eine ferne Abhängigkeit).

Informieren Sie sich über Maven-Abhängigkeiten:

• Introduction to dependency mechanism (maven.org)
• Handhabung von Abhängigkeiten (Lernprogramm)

Die folgenden Diagramme stellen dar, welche Schritte bisher ausgeführt wurden:

MyProject
├── adapters
    │   ├── RSSAdapter
│   │   ├── RSSAdapter-impl.js
│   │   ├── RSSAdapter.xml
│   │   └── filtered.xsl

RSSAdapter
├── pom.xml
    ├── src
    │   └── main
    │       ├── adapter-resources
    │       │   ├── adapter.xml
│       │   └── js
│       │        ├── RSSAdapter-impl.js
│       │        └── filtered.xml

1. Navigieren Sie in Ihrem Dateisystem zum Java-Adapterordner, z. B. zu ../Desktop/JavaAdapters/RSSAdapter.
2. Öffnen Sie ein separates Fenster und navigieren Sie zu Ihrem neuen Maven-Projekt, z. B. zu ../Desktop/MigratedAdapter, und zum Ordner src/main/adapter-resources.
3. Bearbeiten Sie die Datei {adapter-name}.xml. Ersetzen Sie den Inhalt der Datei durch den XML-Inhalt Ihres vorhandenen Adapters (in diesem Beispiel RSSAdapter.xml).
4. Navigieren Sie (für dieses Beispiel) im neuen Adapter zu src/main/java/com/sample/.
5. Ersetzen Sie die vorhandene Java-Datei durch die Java-Dateien Ihres vorhandenen Adapters.

Wenn Sie im vorhandenen Adapter zusätzliche Bibliotheken verwenden, kommen jetzt Maven-Abhängigkeiten ins Spiel. Da Worklight/MobileFirst Studio nicht verwendet wird, wo sich die Bibliotheken im Ordner server/lib oder im Ordner lib des Java-Adapters befanden, müssen Sie die Bibliotheken durch Maven-Abhängigkeiten ersetzen.

1. Gehen Sie zum neu erstellten Maven-Projekt zurück und öffnen Sie die Datei pom.xml auf der Ausgangsebene des Verzeichnisses.
2. Fügen Sie eine Abhängigkeit für Ihren Datenbanktyp hinzu. Sie können auf der Maven-Central-Website nach der entsprechenden Abhängigkeit suchen.
3. In diesem Beispiel wird eine Cloudant-Abhängigkeit verwendet. Fügen Sie im Abschnitt dependencies den folgenden Codeblock hinzu:

   <dependency>
   	<groupId>com.cloudant</groupId>
   	<artifactId>cloudant-client</artifactId>
   	<version>1.2.3</version>
   </dependency>

Informieren Sie sich über Maven-Abhängigkeiten:

• Introduction to dependency mechanism (maven.org)
• Handhabung von Abhängigkeiten (Lernprogramm)

Die folgenden Diagramme stellen dar, welche Schritte bisher ausgeführt wurden:

├── adapters
    │   └── RSSAdapter
    │       ├── RSSAdapter.xml
    │       ├── lib
    │       └── src
    │           └── com
    │               └── sample
    │                   ├── RSSAdapterApplication.java
    │                   └── RSSAdapterResource.java

├── pom.xml
    ├── src
    │   └── main
    │       ├── adapter-resources
    │       │   └── adapter.xml
    │       └── java
    │           └── com
    │               └── sample
    │                   ├── RSSAdapterApplication.java
    │                   └── RSSAdapterResource.java
   └

Migrierten Adapter erstellen

Navigieren Sie in einem Befehlszeilenfenster zum Ordner des Adapters und führen Sie den Befehl mfpdev adapter build aus.

Für die Korrektur solcher Fehler sollte das Maven-Projekt in eine IDE wie IntelliJ importiert werden, wo ein Projektbuild erstellt werden kann. Wenn Sie eine IDE zur Verfügung haben, ist es einfacher die Buildfehler durchzugehen und nacheinander zu korrigieren. Informieren Sie sich über die Verwendung von IntelliJ und Adaptern.

Erstellten Adapter testen

Zum Testen des migrierten Adapters können Sie die MobileFirst CLI verwenden, um Ihre Endpunkte aufzurufen. Sie können auch Swagger in der MobileFirst Operations Console verwenden.

Weitere Informationen zum Testen von Adaptern enthält das Lernprogramm Adapter testen und debuggen.