====== APIs Java ======

Cette page regroupe des liens vers un ensemble d'APIs/bibliothèques Java qui peuvent servir lors des TPs.

===== APIs de log =====

Il existe un certain nombre d'API de log en Java qui sont de bonnes alternatives à ''System.out.println(...)'' quand on programme côté serveur pour surveiller / déboguer. Parmi les plus connues, on citera:
  * [[http://www.slf4j.org/|slf4j]] (api) + possibilité d'utiliser les apis ci-dessous comme backend
  * le package ''javax.util.logging'', fourni avec le JDK
  * [[http://logback.qos.ch/|logback]]
  * [[http://logging.apache.org/log4j/1.2/|log4j]], [[http://logging.apache.org/log4j/2.x/|log4j2]]
  * [[http://commons.apache.org/proper/commons-logging/|commons-logging]]

Ci-dessous quelques lien un guide de mise en oeuvre rapide pour slf4j+logback et pour log4j 1.2

==== slf4j + logback ====

=== maven ===
Dépendance vers logback ([[http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22logback-classic%22|search maven]])
<code xml>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.1.2</version>
</dependency>
</code>

Il y a une dépendance transitive vers slf4j.

=== configuration ===

Mettre un fichier ''logback.xml'' dans le CLASSPATH, e.g. dans ''src/main/resources/'':
<code xml logback.xml>
<configuration>

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <!-- encoders are assigned the type
             ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="STDOUT" />
    </root>

    <logger level="DEBUG" name="mon.paquet.a.deboguer"/>
</configuration>
</code>

Voir la [[http://logback.qos.ch/manual/configuration.html|doc]] pour les détails

=== Utilisation ===

<code java>
...
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
public class Toto {

  private static final Logger LOG = LoggerFactory.getLogger(Toto.class);

  public int truc() {

    // message de debug
    LOG.debug("Coucou");

    // message d'information utilisant un template
    LOG.info("Coucou {}","Titi");

    // message de warning
    LOG.warn("Coucou");

    // message d'erreur
    LOG.error(":-(");
    // ou même
    LOG.error(":-(",monException);

  }
  
}
</code>

==== log4j 1.2 ====

[[http://logging.apache.org/log4j/|Page de log4j]]

[[http://logging.apache.org/log4j/1.2/manual.html|Documentation log4j]]


=== Mise en oeuvre rapide ===

Ajouter le fichier {{:enseignement:sw:log4j-1.2.15.jar|log4j-1.2.15.jar}} (à noter qu'il est déjà intégré dans JBoss) à votre projet.

Créer un fichier ''log4j.properties'' à la racine de votre arborescence de fichiers sources Java avec le contenu suivant:
<code>
log4j.rootLogger=WARN, A1

# Log sur la sortie standard
log4j.appender.A1=org.apache.log4j.ConsoleAppender

log4j.appender.A1.layout=org.apache.log4j.PatternLayout

# Format d'affichage du log
# Print the date in ISO 8601 format
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n

# Print only messages of level WARN or above in the package com.foo.
log4j.logger.com.foo=INFO

</code>

Pour utiliser log4j dans une classe Java, on peut s'inspirer du code suivant:
<code java>
public class Toto {

  private static org.apache.log4j.Logger log = org.apache.log4j.Logger.getLogger(Toto.class);

  ...

  public int truc() {

    // message de debug
    log.debug("Coucou");

    // message d'information
    log.info("Coucou");

    // message de warning
    log.warn("Coucou");

    // message d'erreur
    log.error(":-(");
    // ou même
    log.error(":-(",monException);

  }

}
</code>

=== Intégration via maven ===

Ajouter la dépendance suivante à votre projet Maven:
<code xml>
    <dependency>
        <groupId>log4j</groupId>
        <artifactId>log4j</artifactId>
        <version>1.2.12</version>
    </dependency>
</code>

Le fichier log4j.properties est à placer dans le répertoire ''src/main/resources'' et non pas le le répertoire ''src/main/java''

===== JUnit =====

[[http://www.junit.org/|JUnit]] est une bibliothèque de test unitaire pour Java. Elle est déjà intégrée dans Eclipse J2EE. Pour créer un test en JUnit, il suffit d'étendre la classe ''junit.framework.TestCase''. La cration d'une telle classe peut se faire via un wizard. La première fois, il vous propose ajouter le run-time JUnit, sans quoi il manquera des bibliothèques. 

Dans une telle classe, toute méthode ''public void'' dont le nom commence par ''test'' et ne prenant aucun argument est considérée comme un test à effectuer. Par ailleurs, un ensemble de méthodes sont fournies dans la classe ''TestCase'' facilitant les verifications et la signalisation d'erreur, ce sont les méthodes commençant par ''assert''. Pour lancer des tests dans Eclipse, il suffit d'exécuter une classe de test en tant que //JUnit Test//.

Pour finir, un exemple de classe de test JUnit:
<code java>
package fr.univlyon1.ecoquery;

import junit.framework.TestCase;

public class Test1 extends TestCase {

	int a;
	
	protected void setUp() throws Exception {
		super.setUp();
		// executée 1 fois avant chaque test
		a= 3;
	}

	protected void tearDown() throws Exception {
		super.tearDown();
		// exécutée une fois après chaque test
	}
	
	// Un premier test
	public void testAddition() {
		assertEquals(3, 2+1);
		assertEquals(3,a);
		a = 10;
		assertFalse(3 == 2+5);
		assertTrue(3 == 1+1+1);
		assertFalse(3 == a-2);
		assertNotNull(new Integer(4+2));
	}
	
	// Un test qui échoue
	public void testEchec() {
		assertEquals(3, 2+2);
	}
	
}
</code>

Si vous utilisez un projet maven, tout le code de test, ainsi que les resources servant uniquement au tests sont à placer dans ''src/test'', dont la structuration est similaire à celle de ''src/main'', avec en particulier un répertoire ''java'' et un répertoire ''resources''.
===== Datasources =====

==== JBoss ====

Ajouter un fichier ''xxx-ds.xml''((où xxx est un nom quelconque)) dans le repertoire ''server/default/deploy'' de JBoss.
Le plus simple est de copier le bon fichier à partir du répertoire ''docs/examples/jca'' et de l'adapter à vos besoins.
Ne pas oublier d'ajouter le .jar qui va bien dans le répertoire ''server/default/lib'' s'il n'y est pas déjà.

==== Tomcat ====

Voir [[http://tomcat.apache.org/tomcat-7.0-doc/jndi-datasource-examples-howto.html|Le HOWTO de la doc Tomcat 7.0]]

Ne pas hésiter à mettre la config dans le ''GlobalNamingResources'' (voir la fin du howto). 

Pour les tomcats exécutés via ''mvn tomcat:run'', il est possible de spécifier un fichier de contexte dans le pom: [[http://tomcat.apache.org/maven-plugin-2.1/run-mojo-features.html|voir la doc du plugin]]

===== Hibernate =====

[[http://hibernate.org|Hibernate]] est une implementation de l'API JPA. Les dépendances maven à ajouter pour l'utiliser sont:
<code xml>
        <dependency>
            <groupId>javax.persistence</groupId>
            <artifactId>persistence-api</artifactId>
            <version>1.0</version>
        </dependency>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate</artifactId>
            <version>3.2.6.ga</version>
        </dependency>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-entitymanager</artifactId>
            <version>3.4.0.GA</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>1.4.2</version>
        </dependency>
</code>

Il peut être nécessaire((par exemple en cas d'utilisation conjointe avec Spring ou CXF)) de remplacer:
<code xml>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate</artifactId>
            <version>3.2.6.ga</version>
        </dependency>
</code>
par:
<code xml>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate</artifactId>
            <version>3.2.6.ga</version>
            <exclusions>
                <exclusion>
                    <groupId>asm</groupId>
                    <artifactId>asm</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>asm</groupId>
                    <artifactId>asm-attrs</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>cglib</groupId>
                    <artifactId>cglib</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>asm</groupId>
            <artifactId>asm</artifactId>
            <version>2.2.3</version>
        </dependency>
        <dependency>
            <groupId>cglib</groupId>
            <artifactId>cglib-nodep</artifactId>
            <version>2.1_3</version>
        </dependency>
</code>