Kapitel 4. Änderungen der Serverkonfiguration

Undertow ersetzt JBoss Web als Webserver in JBoss EAP 7. Das bedeutet, dass die Konfiguration des alten web-Subsystems zur neuen JBoss EAP 7 undertow-Subsystemkonfiguration migriert werden muss.

Sie können die migrate-Operation der Management-CLI zur Migration des web-Subsystems zu undertow in der Serverkonfigurationsdatei verwenden. Beachten Sie jedoch, dass diese Operation nicht dazu in der Lage ist, sämtliche Konfigurationen des JBoss Web-Subsystems zu migrieren. Falls Sie »migration-warning«-Einträge sehen, müssen Sie zusätzliche Management-CLI-Befehle ausführen, um diese Konfigurationen zu Undertow zu migrieren. Weitere Informationen über die migrate-Operation der Management-CLI finden Sie unter migrate-Operation der Management-CLI.

Nachfolgend sehen Sie ein Beispiel der standardmäßigen Konfiguration für das web-Subsystem in JBoss EAP 6.

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
    <virtual-server name="default-host" enable-welcome-root="true">
        <alias name="localhost"/>
        <alias name="example.com"/>
    </virtual-server>
</subsystem>

Nachfolgend sehen Sie ein Beispiel der standardmäßigen Konfiguration für das undertow-Subsystem in JBoss EAP 6.

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="server-header"/>
            <filter-ref name="x-powered-by-header"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        <response-header name="server-header" header-name="Server" header-value="JBoss-EAP/7"/>
        <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>
    </filters>
</subsystem>

Die migrate-Operation der Management-CLI ist nicht dazu in der Lage, automatisch »rewrite«-Bedingungen zu migrieren. Diese werden stattdessen als »migration-warnings« gemeldet und müssen manuell migriert werden. Sie können eine äquivalente Konfiguration in JBoss EAP 7 erstellen, indem Sie Prädikat-Attribute und Handler verwenden; für weitere Informationen diesbezüglich siehe Undertow Predicates Attributes and Handlers.

Nachfolgend sehen Sie ein Beispiel einer Konfiguration für das web-Subsystem in JBoss EAP 6, die eine rewrite-Konfiguration beinhaltet.

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default" native="false">
    <virtual-server name="default" enable-welcome-root="true">
        <alias name="localhost"/>
        <rewrite name="test" pattern="(.*)/toberewritten/(.*)" substitution="$1/rewritten/$2" flags="NC"/>
        <rewrite name="test2" pattern="(.*)" substitution="-" flags="F">
            <condition name="get" test="%{REQUEST_METHOD}" pattern="GET"/>
            <condition name="andCond" test="%{REQUEST_URI}" pattern=".*index.html" flags="NC"/>
        </rewrite>
    </virtual-server>
</subsystem>

Folgen Sie den Anweisungen unter migrate-Operation der Management-CLI, um Ihren Server und die Management-CLI zu starten, und migrieren Sie anschließend die Konfigurationsdatei für das web-Subsystem mithilfe des folgenden Befehls.

/subsystem=web:migrate

Die folgenden »migration-warnings« werden gemeldet, wenn Sie die migrate-Operation auf der obigen Konfiguration ausführen.

/subsystem=web:migrate
{
    "outcome" => "success",
    "result" => {"migration-warnings" => [
        "WFLYWEB0002: Could not migrate resource {
    \"pattern\" => \"(.*)\",
    \"substitution\" => \"-\",
    \"flags\" => \"F\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_METHOD}\",
    \"pattern\" => \"GET\",
    \"flags\" => undefined,
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"get\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_URI}\",
    \"pattern\" => \".*index.html\",
    \"flags\" => \"NC\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"andCond\")
    ]
}"
    ]}
}

Wenn Sie die Serverkonfigurationsdatei überprüfen, sehen Sie die folgende Konfiguration für das undertow-Subsystem.

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
     <buffer-cache name="default"/>
     <server name="default-server">
         <http-listener name="http" socket-binding="http"/>
         <host name="default-host" alias="localhost, example.com">
             <location name="/" handler="welcome-content"/>
         </host>
     </server>
     <servlet-container name="default">
         <jsp-config/>
     </servlet-container>
     <handlers>
         <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
     </handlers>
 </subsystem>

Verwenden Sie die Management-CLI, um den Filter anzulegen, der die rewrite-Konfiguration im undertow-Subsystem ersetzen soll. Für jeden Befehl sollten Sie die Meldung »{"outcome" ⇒ "success"}« erhalten.

# Create the filters
/subsystem=undertow/configuration=filter/expression-filter="test1":add(expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')")
/subsystem=undertow/configuration=filter/expression-filter="test2":add(expression="method('GET') and path('.*index.html') -> response-code(403)")

# Add the filters to the default server
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test1":add
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test2":add

Überprüfen Sie die aktualisierte Serverkonfigurationsdatei. Das JBoss Web-Subsystem ist nun vollständig migriert und im undertow-Subsystem konfiguriert.

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="http" socket-binding="http"/>
        <host name="default-host" alias="localhost, example.com">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="test1"/>
            <filter-ref name="test2"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        <expression-filter name="test1" expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')"/>
        <expression-filter name="test2" expression="method('GET') and path('.*index.html') -> response-code(403)"/>
    </filters>
</subsystem>

For more information about how to configure filters and handlers using the management CLI, see Configuring the Web Server in the JBoss EAP 7 Configuration Guide.

In der vorherigen Release von JBoss EAP konnte mithilfe von Systemeigenschaften das standardmäßige Verhalten von JBoss Web verändert werden. Informationen darüber, wie Sie dasselbe Verhalten in Undertow konfigurieren können, finden Sie unter Übersicht über das Migrieren von JBoss Web Systemeigenschaften

In JBoss EAP 6, JBoss Web supported the ability to specify additional static files for a web application using the overlay element in the jboss-web.xml file. This feature did not actually overlay existing files, but instead added static files to a deployment outside of the WAR archive.

In the following jboss-web.xml file example, /tmp/mycontents/test.html was returned by the JBoss EAP 6 server when you accessed the URL http://localhost:8080/example/test.html.

<jboss-web>
    <context-root>/example</context-root>
    <overlay>/tmp/mycontents/</overlay>
</jboss-web>

Undertow, which replaces JBoss Web in JBoss EAP 7, does not support the jboss-web.xml file overlay feature.

Frühere Versionen von JBoss EAP unterstützten Valves. Valves sind angepasste Klassen, die in die anfrageverarbeitende Pipeline für eine Applikation vor Servlet-Filtern eingefügt werden, um Änderungen an der Anfrage durchzuführen oder zusätzliche Verarbeitungen durchzuführen.

Dieser Abschnitt beschreibt die Migration von globalen Valves. Die Migration von angepassten und Authenticator Valves wird im Abschnitt Migrieren von angepassten Applikations-Valves dieses Handbuchs erläutert.

Undertow, das JBoss Web in JBoss EAP 7 ersetzt, unterstützt keine globalen Valves. Sie sollten jedoch eine ähnliche Funktion erreichen können mithilfe von Undertow-Handlern. Undertow enthält eine Reihe von integrierten Handlern, die allgemeine Funktionen bereitstellen. Es bietet auch die Möglichkeit zur Erstellung von angepassten Handlern, die als Ersatz für die Funktionen angepasster Valves dienen können.

Falls Ihre Applikation Valves verwendet, müssen Sie diese durch den jeweiligen Undertow Handler-Code ersetzen, um dieselbe Funktionalität zu erreichen, wenn Sie zu JBoss EAP 7 migrieren.

For more information about how to configure handlers, see Configuring Handlers in the JBoss EAP 7 Configuration Guide.

For more information about how to configure filters, see Configuring Filters in the JBoss EAP 7 Configuration Guide.

Migrieren von JBoss Web Valves

Die folgende Tabelle führt die Valves auf, die in der vorherigen Release von JBoss EAP von JBoss Web bereitgestellt wurden, sowie die jeweiligen integrierten Handler in Undertow. Die JBoss Web Valves befinden sich im Paket org.apache.catalina.valves.

Sie können die migrate-Operation der Management-CLI verwenden, um automatisch globale Valves zu migrieren, welche die folgenden Kriterien erfüllen:

Weitere Informationen über die migrate-Operation der Management-CLI finden Sie unter migrate-Operation der Management-CLI .

Manuelles Migrationsverfahren für JDBCAccessLogValve

Die Valve org.apache.catalina.valves.JDBCAccessLogValve ist eine Ausnahme und kann nicht automatisch zu io.undertow.server.handlers.JDBCLogHandler migriert werden. Folgen Sie den nachstehenden Anweisungen, um die folgende Beispiel-Valve zu migrieren.

<valve name="jdbc" module="org.jboss.as.web" class-name="org.apache.catalina.valves.JDBCAccessLogValve">
    <param param-name="driverName" param-value="com.mysql.jdbc.Driver" />
    <param param-name="connectionName" param-value="root" />
    <param param-name="connectionPassword" param-value="password" />
    <param param-name="connectionURL" param-value="jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull" />
    <param param-name="format" param-value="combined" />
</valve>

In der Standardkonfiguration von JBoss EAP 6 verwendete JGroups die public-Schnittstelle, die im Abschnitt <interfaces> der Serverkonfigurationsdatei definiert war.

Da empfohlen wird, eine dedizierte Netzwerkschnittstelle zu nutzen, verwendet JGroups standardmäßig nunmehr die neue private-Schnittstelle, die in JBoss EAP 7 im Abschnitt <interfaces> der Serverkonfigurationsdatei definiert ist.

JGroups bietet Unterstützung für Gruppenkommunikation von HA-Services in Form von JGroups-Channels. JBoss EAP 7 führt <channel>-Elemente zum jgroups-Subsystem in der Serverkonfigurationsdatei ein. Mithilfe der Management-CLI können Sie die Konfiguration von JGroups-Channels hinzufügen, entfernen oder ändern.

For more information about how to configure JGroups, see Cluster Communication with JGroups in the JBoss EAP Configuration Guide.

In JBoss EAP 6, the default clustered caches for web session replication and EJB replication were replicated ASYNC caches. This has changed in JBoss EAP 7. The default clustered caches are now distributed ASYNC caches. The replicated caches are no longer even configured by default. See Configure the Cache Mode in the JBoss EAP Configuration Guide for information about how to add a replicated cache and make it the default.

Dies betrifft Sie nur, wenn Sie die neue Standardkonfiguration von JBoss EAP 7 verwenden. Falls Sie die Konfiguration von JBoss EAP 6 migrieren, bleibt die Konfiguration des infinispan-Subsystems erhalten.

Das Verhalten der ASYNC-Cache-Strategie hat sich in JBoss EAP 7 geändert.

In JBoss EAP 6 erfolgten Lesevorgänge im ASYNC-Cache ohne Sperre. Obwohl dies nie ein Blockieren zur Folge hatte, war dieses Verhalten anfällig für das Lesen veralteter Daten, beispielsweise beim Failover, denn nachfolgende Anfragen für denselben Benutzer durften starten, bevor die vorherige Anfrage abgeschlossen war. Diese Toleranz ist im verteilten Modus nicht akzeptabel, da Änderungen in der Cluster-Topologie Auswirkungen auf die Session-Affinität haben kann und leicht zu veralteten Daten führen kann.

In JBoss EAP 7 erfordern Lesevorgänge im ASYNC-Cache Sperren. Da nun neue Anfragen vom selben Benutzer gesperrt werden, bis die vorherige Replikation abgeschlossen ist, ist das Lesen veralteter Daten somit ausgeschlossen.

Die Modulerweiterung org.jboss.as.messaging in EAP_HOME/modules/system/layers/base/ wurde ersetzt durch das Erweiterungsmodul org.wildfly.extension.messaging-activemq.

Der Namespace urn:jboss:domain:web:2.2 der Subsystemkonfiguration wurde ersetzt durch den Namespace urn:jboss:domain:messaging-activemq:1.0.

Management-Modell

In den meisten Fällen wurde versucht, die Element- und Attributnamen möglichst unverändert zu jenen der vorherigen Releases zu halten. Die folgende Tabelle zeigt einige der Änderungen.

Die Management-Operationen, die auf dem neuen messaging-activemq-Subsystem aufgerufen werden, haben sich geändert von /subsystem=messaging/hornetq-server= zu /subsystem=messaging-activemq/server=.

Sie können eine vorhandene JBoss EAP 6 messaging-Subsystemkonfiguration zum messaging-activemq-Subsystem auf einem JBoss EAP 7 Server migrieren, indem Sie dessen migrate-Operation ausführen.

/subsystem=messaging:migrate

Before you execute the migrate operation, you can invoke the describe-migration operation to review the list of management operations that will be performed to migrate from the existing JBoss EAP 6 messaging subsystem configuration to the messaging-activemq subsystem on the JBoss EAP 7 server.

/subsystem=messaging:describe-migration

Die Operationen migrate und describe-migration zeigen auch eine Liste mit migration-warnings für Ressourcen oder Attribute an, die nicht automatisch migriert werden können.

Migration und Aufwärtskompatibilität des Messaging-Subsystems

Die Operationen describe-migration und migrate für das messaging-Subsystem bieten einen zusätzlichen Konfigurationsparameter. Falls Sie das Messaging so konfigurieren möchten, dass alte JBoss EAP 6 Clients sich mit dem JBoss EAP 7 Server verbinden dürfen, können Sie die boolesche Variable add-legacy-entries wie folgt den Operationen describe-migration oder migrate hinzufügen.

/subsystem=messaging:describe-migration(add-legacy-entries=true)
/subsystem=messaging:migrate(add-legacy-entries=true)

Falls die boolesche Variable add-legacy-entries auf true gesetzt ist, erstellt das messaging-activemq-Subsystem die Ressource legacy-connection-factory und fügt legacy-entries zu den Ressourcen jms-queue und jms-topic hinzu.

Falls die boolesche Variable add-legacy-entries auf false gesetzt ist, werden keine alten Ressourcen im messaging-activemq-Subsystem erstellt, weshalb alte JMS-Clients nicht mit den JBoss EAP 7 Servern kommunizieren werden können. Dies ist der Standardwert.

For more information about forward and backward compatibility see the Backward and Forward Compatibility in Configuring Messaging for JBoss EAP.

Weitere Informationen über die Operationen migrate und describe-migration der Management-CLI finden Sie unter migrate-Operation der Management-CLI .

Geändertes Verhalten des forward-when-no-consumers Attributs

Das Verhalten des Attributs forward-when-no-consumers hat sich in JBoss EAP 7 geändert.

Wenn forward-when-no-consumers in JBoss EAP 6 auf false gesetzt war und keine Verbraucher im Cluster vorhanden waren, dann wurden Nachrichten auf alle Knoten in einem Cluster weiterverteilt.

Dieses Verhalten hat sich in JBoss EAP 7 geändert. Wenn forward-when-no-consumers auf false gesetzt ist und keine Verbraucher im Cluster vorhanden sind, dann werden Nachrichten nicht weiterverteilt. Stattdessen verbleiben die Nachrichten auf dem Knoten, an den sie gesendet wurden.

Änderungen der Messaging-Subsystem-XML-Konfiguration

Die XML-Konfiguration hat sich mit dem neuen messaging-activemq-Subsystem grundlegend geändert und bietet nun ein XML-Schema, das eher im Einklang mit anderen JBoss EAP Subsystemen steht.

It is strongly advised that you do not attempt to modify the JBoss EAP messaging subsystem XML configuration to conform to the new messaging-activemq subsystem. Instead, invoke the legacy subsystem migrate operation. This operation will write the XML configuration of the new messaging-activemq subsystem as a part of its execution.

Aufgrund des Wechsels von HornetQ zu ActiveMQ Artemis als JMS-Support-Provider haben sich sowohl das Format als auch der Speicherort für die Messaging-Daten in JBoss EAP 7 geändert.

Sie können eine der beiden folgenden Herangehensweisen wählen, um die Daten zu migrieren:

Unter Zuordnung der Messaging-Verzeichnisnamen finden Sie Details über die Änderungen an den Verzeichnisnamen für Messaging-Daten zwischen den Releases.

java -jar -mp MODULE_PATH org.hornetq.exporter MESSAGING_BINDINGS_DIRECTORY MESSAGING_JOURNAL_DIRECTORY MESSAGING_PAGING_DIRECTORY MESSAGING_LARGE_MESSAGES_DIRECTORY > OUTPUT_DATA.xml

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.hornetq.exporter">
    <main-class name="org.hornetq.jms.persistence.impl.journal.XmlDataExporter"/>
    <properties>
        <property name="jboss.api" value="deprecated"/>
    </properties>
    <dependencies>
        <module name="org.hornetq"/>
    </dependencies>
</module>

/subsystem=messaging-activemq/server=default:import-journal(file=OUTPUT_DIRECTORY/OldMessagingData.xml)

In vorherigen Releases von JBoss EAP wurden JMS-Zielwarteschlangen im <jms-destinations>-Element unter dem <hornetq-server>-Element im messaging-Subsystem konfiguriert.

<hornetq-server>
  ...
  <jms-destinations>
     <jms-queue name="testQueue">
        <entry name="queue/test"/>
         <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
  </jms-destinations>
  ...
</hornetq-server>

In JBoss EAP 7 wird die JMS-Zielwarteschlange im standardmäßigen <server>-Element des messaging-activemq-Subsystems konfiguriert.

<server name="default">
  ...
  <jms-queue name="testQueue" entries="queue/test java:jboss/exported/jms/queue/test"/>
  ...
</server>

Messaging-Interzeptoren haben sich in JBoss EAP 7 grundlegend geändert, da HornetQ durch ActiveMQ Artemis als JMS Messaging Provider ersetzt wurde.

Um beim HornetQ messaging-Subsystem, das in der vorherigen Release von JBoss EAP enthalten war, HornetQ-Interzeptoren zu installieren, mussten Sie diese einem JAR hinzufügen und dann die HornetQ module.xml-Datei bearbeiten.

The messaging-activemq subsystem included in JBoss EAP 7 does not require modification of a module.xml file. User interceptor classes, which now implement the Apache ActiveMQ Artemis Interceptor interface, can now be loaded from any server module. You specify the module from which the interceptor should be loaded in the messaging-activemq subsystem of the server configuration file.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <incoming-interceptors>
      <class name="com.mycompany.incoming.myInterceptor" module="com.mycompany" />
      <class name="com.othercompany.incoming.myOtherInterceptor" module="com.othercompany" />
    </incoming-interceptors>
    <outgoing-interceptors>
      <class name="com.mycompany.outgoing.myInterceptor" module="com.mycompany" />
      <class name="com.othercompany.outgoing.myOtherInterceptor" module="com.othercompany" />
    </outgoing-interceptors>
  </server>
</subsystem>

In JBoss EAP 6 konnten Sie eine Servlet-Engine für die Arbeit mit dem Netty-Servlet-Transport konfigurieren. Da ActiveMQ Artemis nun HornetQ als integrierten Messaging-Provider in JBoss EAP 7 ersetzt, steht diese Konfiguration nicht mehr zur Verfügung. Sie müssen die Servlet-Konfiguration durch die neuen integrierten http-Connectors und http-Acceptors ersetzen.

Bei der Konfiguration einer Datasource in der vorherigen Release von JBoss EAP hing der Wert für den Treibernamen von der Anzahl der Klassen in der Datei META-INF/services/java.sql.Driver ab, die im JDBC-Treiber-JAR enthalten war.

Treiber mit einer einzelnen Klasse

Falls die Datei META-INF/services/java.sql.Driver nur eine einzige Klasse spezifizierte, dann war der Wert für den Treibernamen einfach der Name des JDBC-Treiber-JARs. Dies hat sich in JBoss EAP 7 nicht geändert.

Treiber mit mehreren Klassen

Falls in JBoss EAP 6 mehr als eine Klasse in der Datei META-INF/services/java.sql.Driver aufgeführt war, dann gaben Sie an, bei welcher Klasse es sich um die Treiberklasse handelte, indem Sie deren Namen sowie die Haupt- und Nebenversion im folgenden Format an den JAR-Namen anfügten:

JAR_NAME + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION

In JBoss EAP 7 wurde dies geändert. Sie geben den Treibernamen nun im folgenden Format an:

JAR_NAME + "_" + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION

Der MySQL 5.1.31 JDBC-Treiber ist ein Beispiel für einen Treiber, der zwei Klassen enthält. Der Name der Treiberklasse lautet com.mysql.jdbc.Driver. Die folgenden Beispiele veranschaulichen die Unterschiede in der Art und Weise, wie Sie den Treibernamen in der vorherigen Release von JBoss EAP im Vergleich zur aktuellen Release angeben.

mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1

mysql-connector-java-5.1.31-bin.jar_com.mysql.jdbc.Driver_5_1