Configurare le origini dati per un'app Tomcat, JBoss o Java SE nel servizio app di Azure

Questo articolo illustra come configurare le origini dati in un'app Java SE, Tomcat o JBoss nel servizio app.

Il servizio app di Azure esegue applicazioni Web Java in un servizio completamente gestito in tre varianti:

• Java SE: può eseguire un'app distribuita come pacchetto JAR che contiene un server incorporato (ad esempio Spring Boot, Dropwizard, Quarkus o uno con un server Tomcat o Jetty incorporato).
• Tomcat: il server Tomcat predefinito può eseguire un'app distribuita come pacchetto WAR.
• JBoss EAP: supportato per le app Linux solo nei piani tariffari Premium v3 e Isolato v2. Il server JBoss EAP predefinito può eseguire un'app distribuita come pacchetto WAR o EAR.

Nota

Per le applicazioni Spring, è consigliabile usare Azure Spring Apps. Tuttavia, è comunque possibile usare il Servizio app di Azure come destinazione. Per consigli, vedere Indicazioni sulla destinazione del carico di lavoro Java.

Configurare l'origine dati

Per connettersi alle origini dati nelle applicazioni Spring Boot, è consigliabile creare stringhe di connessione e inserirle nel file application.properties.

1. Nella sezione "Configurazione" della pagina del Servizio app di Azure, impostare un nome per la stringa, incollare la stringa di connessione JDBC nel campo valore e impostare il tipo su "Personalizzato". Facoltativamente, è possibile impostare questa stringa di connessione come impostazione dello slot.

   Questa stringa di connessione è accessibile all'applicazione come variabile di ambiente denominata CUSTOMCONNSTR_<your-string-name>. Ad esempio: CUSTOMCONNSTR_exampledb.

2. Nel file application.properties, fare riferimento a questa stringa di connessione con il nome della variabile di ambiente. Per questo esempio si userà il codice seguente:

   app.datasource.url=${CUSTOMCONNSTR_exampledb}
   

Per altre informazioni, vedere la documentazione Spring Boot sull'accesso ai dati e configurazioni esterne.

Suggerimento

Per impostazione predefinita, i contenitori Tomcat Linux possono configurare automaticamente le origini dati condivise nel server Tomcat. L'unica cosa da fare è aggiungere un'impostazione dell'app che contiene una stringa di connessione JDBC valida a un database Oracle, SQL Server, PostgreSQL o MySQL (incluse le credenziali di connessione) e il servizio app aggiunge automaticamente il database condiviso che risponde a /usr/local/tomcat/conf/context.xml, usando un driver appropriato disponibile nel contenitore. Per uno scenario end-to-end con questo approccio, vedere Esercitazione: Creare un'app Web Tomcat con il servizio app di Azure in Linux e MySQL.

Queste istruzioni si applicano a tutte le connessioni di database. È necessario sostituire i segnaposto con il nome della classe del driver del database scelto e il file JAR. Viene fornita una tabella con i nomi delle classi e i download dei driver per i database più comuni.

Database	Nome della classe del driver	Driver JDBC
PostgreSQL	org.postgresql.Driver	Scaricare
MySQL	com.mysql.jdbc.Driver	Scaricare (selezionare "Indipendente dalla piattaforma")
SQL Server	com.microsoft.sqlserver.jdbc.SQLServerDriver	Scaricare

Per configurare Tomcat per l'uso di Java Database Connectivity (JDBC) o Java Persistence API (JPA), personalizzare prima la variabile di ambiente CATALINA_OPTS letta da Tomcat all'avvio. Impostare questi valori tramite un'impostazione app nel plug-in Maven del servizio app:

<appSettings>
    <property>
        <name>CATALINA_OPTS</name>
        <value>"$CATALINA_OPTS -Ddbuser=${DBUSER} -Ddbpassword=${DBPASSWORD} -DconnURL=${CONNURL}"</value>
    </property>
</appSettings>

In alternativa, impostare le variabili di ambiente nella pagina Configurazione>Impostazioni dell'applicazione nel portale di Azure.

Determinare quindi se l'origine dati deve essere disponibile per un'applicazione o per tutte le applicazioni in esecuzione nel servlet Tomcat.

Origini dati a livello di applicazione

1. Creare un file context.xml nella directory META-INF/ del progetto. Creare la directory META-INF/, se non esiste.

2. In context-xml aggiungere un elemento Context per collegare l'origine dati a un indirizzo JNDI. Sostituire il segnaposto driverClassName con il nome della classe del driver indicato nella tabella precedente.

   <Context>
       <Resource
           name="jdbc/dbconnection"
           type="javax.sql.DataSource"
           url="${connURL}"
           driverClassName="<insert your driver class name>"
           username="${dbuser}"
           password="${dbpassword}"
       />
   </Context>
   

3. Aggiornare il file web.xml dell'applicazione per usare l'origine dati nell'applicazione.

   <resource-env-ref>
       <resource-env-ref-name>jdbc/dbconnection</resource-env-ref-name>
       <resource-env-ref-type>javax.sql.DataSource</resource-env-ref-type>
   </resource-env-ref>
   

Risorse a livello di server condiviso

Linux

L'aggiunta di un'origine dati condivisa a livello di server richiede di modificare il server.xml di Tomcat. Il modo più affidabile per eseguire questa operazione è il seguente:

1. Per prima cosa, caricare uno script di avvio e impostare il percorso dello script in Configurazione>Comando di avvio. È possibile caricare lo script di avvio usando FTP.

Lo script di avvio crea una trasformazione xsl nel file server.xml e restituisce il file XML risultante in /usr/local/tomcat/conf/server.xml. Lo script di avvio deve installare libxslt tramite apk. Il file xsl e lo script di avvio possono essere caricati tramite FTP. Di seguito è riportato uno script di avvio di esempio.

# Install libxslt. Also copy the transform file to /home/tomcat/conf/
apk add --update libxslt

# Usage: xsltproc --output output.xml style.xsl input.xml
xsltproc --output /home/tomcat/conf/server.xml /home/tomcat/conf/transform.xsl /usr/local/tomcat/conf/server.xml

Il file XSL di esempio seguente aggiunge un nuovo nodo connettore al server.xml Tomcat.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="@* | node()" name="Copy">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()"/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="@* | node()" mode="insertConnector">
    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                 contains(., '&lt;Connector') and
                                 (contains(., 'scheme=&quot;https&quot;') or
                                  contains(., &quot;scheme='https'&quot;))]">
    <xsl:value-of select="." disable-output-escaping="yes" />
  </xsl:template>

  <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                   comment()[contains(., '&lt;Connector') and
                                             (contains(., 'scheme=&quot;https&quot;') or
                                              contains(., &quot;scheme='https'&quot;))]
                                  )]
                      ">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()" mode="insertConnector" />
    </xsl:copy>
  </xsl:template>

  <!-- Add the new connector after the last existing Connnector if there's one -->
  <xsl:template match="Connector[last()]" mode="insertConnector">
    <xsl:call-template name="Copy" />

    <xsl:call-template name="AddConnector" />
  </xsl:template>

  <!-- ... or before the first Engine if there's no existing Connector -->
  <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                mode="insertConnector">
    <xsl:call-template name="AddConnector" />

    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template name="AddConnector">
    <!-- Add new line -->
    <xsl:text>&#xa;</xsl:text>
    <!-- This is the new connector -->
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
               maxThreads="150" scheme="https" secure="true" 
               keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
               clientAuth="false" sslProtocol="TLS" />
  </xsl:template>

</xsl:stylesheet>

Completare la configurazione

Infine, inserire i file driver con estensione jar nel classpath Tomcat e riavviare il Servizio app di Azure.

1. Assicurarsi che i file driver JDBC siano disponibili per il caricatore di classe Tomcat inserendoli nella directory /home/site/lib. In Cloud Shell eseguire az webapp deploy --type=lib per ogni file JAR del driver:

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --path <jar-name>.jar

Se è stata creata un'origine dati a livello di server, riavviare l'applicazione Linux del Servizio app. Tomcat reimposta CATALINA_BASE su /home/tomcat e usa la configurazione aggiornata.

Windows

Non è possibile modificare direttamente un'installazione Tomcat per la configurazione a livello di server perché il percorso di installazione è di sola lettura. Per apportare modifiche alla configurazione a livello di server all'installazione di Windows Tomcat, il modo più semplice consiste nell'eseguire le operazioni seguenti all'avvio dell'app:

1. Copiare Tomcat in una directory locale (%LOCAL_EXPANDED%) e usarla come CATALINA_BASE (vedere la documentazione di Tomcat in questa variabile).
2. Aggiungere le origini dati condivise a %LOCAL_EXPANDED%\tomcat\conf\server.xml usando la trasformazione XSL.

Aggiungere un file di avvio

Creare un file denominato startup.cmd %HOME%\site\wwwroot directory. Questo file viene eseguito automaticamente prima dell'avvio del server Tomcat. Il file deve avere il contenuto seguente:

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -File  %HOME%\site\configure.ps1

Aggiungere lo script di configurazione di PowerShell

Aggiungere quindi lo script di configurazione denominato configure.ps1 alla directory %HOME%_\site con il codice seguente:

# Locations of xml and xsl files
$target_xml="$Env:LOCAL_EXPANDED\tomcat\conf\server.xml"
$target_xsl="$Env:HOME\site\server.xsl"

# Define the transform function
# Useful if transforming multiple files
function TransformXML{
    param ($xml, $xsl, $output)

    if (-not $xml -or -not $xsl -or -not $output)
    {
        return 0
    }

    Try
    {
        $xslt_settings = New-Object System.Xml.Xsl.XsltSettings;
        $XmlUrlResolver = New-Object System.Xml.XmlUrlResolver;
        $xslt_settings.EnableScript = 1;

        $xslt = New-Object System.Xml.Xsl.XslCompiledTransform;
        $xslt.Load($xsl,$xslt_settings,$XmlUrlResolver);
        $xslt.Transform($xml, $output);
    }

    Catch
    {
        $ErrorMessage = $_.Exception.Message
        $FailedItem = $_.Exception.ItemName
        echo  'Error'$ErrorMessage':'$FailedItem':' $_.Exception;
        return 0
    }
    return 1
}

# Start here

# Check for marker file indicating that config has already been done
if(Test-Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker"){
    return 0
}

# Delete previous Tomcat directory if it exists
# In case previous config isn't completed or a new config should be forcefully installed
if(Test-Path "$Env:LOCAL_EXPANDED\tomcat"){
    Remove-Item "$Env:LOCAL_EXPANDED\tomcat" Recurse
}

md -Path "$Env:LOCAL_EXPANDED\tomcat"

# Copy Tomcat to local
# Using the environment variable $AZURE_TOMCAT90_HOME uses the 'default' version of Tomcat
New-Item "$Env:LOCAL_EXPANDED\tomcat" -ItemType Directory
Copy-Item -Path "$Env:AZURE_TOMCAT90_HOME\*" "$Env:LOCAL_EXPANDED\tomcat" -Recurse

# Perform the required customization of Tomcat
$success = TransformXML -xml $target_xml -xsl $target_xsl -output $target_xml

# Mark that the operation was a success if successful
if($success){
    New-Item -Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker" -ItemType File
}

Questo PowerShell completa i passaggi seguenti:

1. Controllare se esiste già una copia Tomcat personalizzata. In caso affermativo, lo script di avvio può terminare qui.
2. Copiare Tomcat in locale.
3. Aggiungere origini dati condivise alla configurazione di Tomcat personalizzata usando la trasformazione XSL.
4. Indicare che la configurazione è stata completata correttamente.

Aggiungere un file di trasformazione XSL

Un caso d'uso comune per personalizzare l'installazione predefinita di Tomcat consiste nel modificare i file di configurazione server.xml, context.xml o web.xml Tomcat. Il servizio app modifica già questi file per fornire funzionalità della piattaforma. Per continuare a usare queste funzionalità, è importante conservare il contenuto di questi file quando si apportano modifiche. A tale scopo, usare una trasformazione XSL (XSLT).

Aggiungere un file di trasformazione XSL denominato configure.ps1 alla directory %HOME%_\site. È possibile usare il codice di trasformazione XSL seguente per aggiungere un nuovo nodo connettore a server.xml. La trasformazione dell'identità all'inizio mantiene il contenuto originale del file di configurazione.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="xml" indent="yes"/>

    <!-- Identity transform: this ensures that the original contents of the file are included in the new file -->
    <!-- Ensure that your transform files include this block -->
    <xsl:template match="@* | node()" name="Copy">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()"/>
      </xsl:copy>
    </xsl:template>

    <xsl:template match="@* | node()" mode="insertConnector">
      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                   contains(., '&lt;Connector') and
                                   (contains(., 'scheme=&quot;https&quot;') or
                                    contains(., &quot;scheme='https'&quot;))]">
      <xsl:value-of select="." disable-output-escaping="yes" />
    </xsl:template>

    <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                     comment()[contains(., '&lt;Connector') and
                                               (contains(., 'scheme=&quot;https&quot;') or
                                                contains(., &quot;scheme='https'&quot;))]
                                    )]
                        ">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()" mode="insertConnector" />
      </xsl:copy>
    </xsl:template>

    <!-- Add the new connector after the last existing Connnector if there's one -->
    <xsl:template match="Connector[last()]" mode="insertConnector">
      <xsl:call-template name="Copy" />

      <xsl:call-template name="AddConnector" />
    </xsl:template>

    <!-- ... or before the first Engine if there's no existing Connector -->
    <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                  mode="insertConnector">
      <xsl:call-template name="AddConnector" />

      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template name="AddConnector">
      <!-- Add new line -->
      <xsl:text>&#xa;</xsl:text>
      <!-- This is the new connector -->
      <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
                 maxThreads="150" scheme="https" secure="true" 
                 keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
                 clientAuth="false" sslProtocol="TLS" />
    </xsl:template>

</xsl:stylesheet>

Configurare l'impostazione dell'app CATALINA_BASE

La piattaforma deve anche sapere dove è installata la versione personalizzata di Tomcat. È possibile configurare il percorso dell'installazione nell'impostazione dell'app CATALINA_BASE.

È possibile usare l'interfaccia della riga di comando di Azure per modificare questa impostazione:

    az webapp config appsettings set -g $MyResourceGroup -n $MyUniqueApp --settings CATALINA_BASE="%LOCAL_EXPANDED%\tomcat"

In alternativa, è possibile modificare manualmente l'impostazione nel portale di Azure:

1. Passare a Impostazioni>Configurazione>Impostazioni applicazione.
2. Selezionare Nuova impostazione applicazione.
3. Usare questi valori per creare l'impostazione:
   1. Nome: CATALINA_BASE
   2. Valore: "%LOCAL_EXPANDED%\tomcat"

Completare la configurazione

Infine, inserire i file driver con estensione JAR nel classpath Tomcat e riavviare il Servizio app di Azure. Assicurarsi che i file driver JDBC siano disponibili per il caricatore di classe Tomcat inserendoli nella directory /home/site/lib. In Cloud Shell eseguire az webapp deploy --type=lib per ogni file JAR del driver:

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --target-path <jar-name>.jar

Durante la registrazione di un'origine dati con JBoss EAP sono necessari tre passaggi principali: caricamento del driver JDBC, aggiunta del driver JDBC come modulo e registrazione del modulo. Il servizio app è un servizio di hosting senza stato, quindi i comandi di configurazione per l'aggiunta e la registrazione del modulo dell'origine dati devono essere inseriti in script e applicati all'avvio del contenitore.

1. Ottenere il driver JDBC del database.

2. Creare un file di definizione del modulo XML per il driver JDBC. L'esempio seguente illustra una definizione di modulo per PostgreSQL.

   <?xml version="1.0" ?>
   <module xmlns="urn:jboss:module:1.1" name="org.postgres">
       <resources>
       <!-- ***** IMPORTANT : REPLACE THIS PLACEHOLDER *******-->
       <resource-root path="/home/site/deployments/tools/postgresql-42.2.12.jar" />
       </resources>
       <dependencies>
           <module name="javax.api"/>
           <module name="javax.transaction.api"/>
       </dependencies>
   </module>
   

3. Inserire i comandi dell'interfaccia della riga di comando di JBoss in un file denominato jboss-cli-commands.cli. I comandi JBoss devono aggiungere il modulo e registrarlo come origine dati. L'esempio seguente illustra i comandi dell'interfaccia della riga di comando di JBoss per PostgreSQL.

   #!/usr/bin/env bash
   module add --name=org.postgres --resources=/home/site/deployments/tools/postgresql-42.2.12.jar --module-xml=/home/site/deployments/tools/postgres-module.xml
   
   /subsystem=datasources/jdbc-driver=postgres:add(driver-name="postgres",driver-module-name="org.postgres",driver-class-name=org.postgresql.Driver,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
   
   data-source add --name=postgresDS --driver-name=postgres --jndi-name=java:jboss/datasources/postgresDS --connection-url=${POSTGRES_CONNECTION_URL,env.POSTGRES_CONNECTION_URL:jdbc:postgresql://db:5432/postgres} --user-name=${POSTGRES_SERVER_ADMIN_FULL_NAME,env.POSTGRES_SERVER_ADMIN_FULL_NAME:postgres} --password=${POSTGRES_SERVER_ADMIN_PASSWORD,env.POSTGRES_SERVER_ADMIN_PASSWORD:example} --use-ccm=true --max-pool-size=5 --blocking-timeout-wait-millis=5000 --enabled=true --driver-class=org.postgresql.Driver --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --jta=true --use-java-context=true --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
   

4. Creare uno script di avvio, startup_script.sh che chiama i comandi dell'interfaccia della riga di comando di JBoss. Nell'esempio seguente viene illustrato come chiamare jboss-cli-commands.cli. Successivamente, si configurerà il servizio app per eseguire questo script all'avvio del contenitore.

   $JBOSS_HOME/bin/jboss-cli.sh --connect --file=/home/site/deployments/tools/jboss-cli-commands.cli
   

5. Usando un client FTP di propria scelta, caricare il driver JDBC, jboss-cli-commands.cli, startup_script.sh e la definizione del modulo in /site/deployments/tools/.

6. Configurare il sito per l'esecuzione startup_script.sh all'avvio del contenitore. Nel portale di Azure passare a Configurazione>Impostazioni generali>Comando di avvio. Impostare il campo del comando di avvio su /home/site/deployments/tools/startup_script.sh. Selezionare Salva per salvare le modifiche.

Per verificare che l'origine dati sia stata aggiunta al server JBoss, eseguire SSH nell'app Web ed eseguire $JBOSS_HOME/bin/jboss-cli.sh --connect. Dopo aver eseguito la connessione a JBoss, eseguire il /subsystem=datasources:read-resource per stampare un elenco delle origini dati.

Passaggi successivi

Per trovare guide introduttive di Azure, esercitazioni e documentazione di riferimento su Java, visitare la pagina Azure per sviluppatori Java.

• Domande frequenti sul Servizio app di Azure in Linux
• Informazioni di riferimento sulle variabili di ambiente e impostazioni dell'app