CXF jest połączeniem kilku bibliotek - YOKO, Celtixa oraz XFire. Każda z nich wcześniej realizowała pewien fragment obecnej funkcjonalności CXF - YOKO obsługuje Corbę a XFire usługi sieciowe. Obecne CXF jest gotowy do używania "produkcyjnego", ponieważ niedawno wyszedł z fazy inkubacji. :)

Architektura

CXF ma dosyć elastyczną budowę. Zgodnie z dokumentacją można wyróżnić najważniejsze składowe:

• Bus, jest trzonem architektury CXF w którym definiuje i konfiguruje się rozszerzenia.
• Messaging & Interceptors, zapewniają niskopoziomowy dostęp do komunikatów oraz warstwę na której jest oparta większość funkcjonalności.
• Front ends, frontendy są interfejsami programistycznymi do tworzenia usług (np. JAX-WS).
• Services, usługi zapewniają model wraz z opisem
• Bidings, element ten jest odpowiedzialny za obsługę konkretnego protokołu (SOAP, REST, Corba etc).
• Transports, warstwa abstrakcji ułatwiająca zmianę sposobu transportu do/z usług.

Markieting :)

CXF oferuje infrastrukturę konieczną do budowania usług, z najważniejszy zalet można wymienić:

• Wsparcie dla różnych protokołów.
• Obsługa standardów WS-*, tj. WS-Addressing, WS-Security, WS-ReliableMessaging, oraz WS-Policy.
• Obsługa wielu transportów.
• Dołączane data-bindingi (np JAXB, Aegis).
• Jasny podział front endów takich jak JAX-WS od najważniejszego kodu.
• Wysoka wydajność.
• Możliwość osadzania w różnych środowiskach.

Z dodatkowych zalet, mogę dodać - bardzo łatwą integrację ze Springiem.

Pierwsza usługa

Do budowania projektów będziemy używać Mavena. Implementowana usługa będzie oparta o frontend JAX-WS z ręcznie pisanym deskryptorem usługi (WSDL first). Jakkolwiek w bardzo prosty sposób można odwrócić kolejność i przy pomocy pluginu CXF do Mavena wygenerować deskryptor.

Struktura projektów będzie następująca:

• parent
  Rodzic projektu ze zdefiniowanymi wersjami bibliotek i raportami.
• contract
  Definicje używane zarówno przez klienta jak i serwer - WSDL oraz konfiguracja pluginu CXF.
• client
  Prosta biblioteka kliencka oparta o mechanizmy CXFa (JaxWSProxyFactoryBean).
• server
  Przykładowa implementacja usługi z bardzo prostym wykorzystaniem Springa.
• webapp
  Konfiguracja transporty CXF - w tym konkretnym przypadku servletu CXF.

Parent

Poniżej znajduje się deskryptor projektu, który jest używany do budowania całości.

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!-- Informacja dla Mavena -->
    <modelVersion>4.0.0</modelVersion>

    <!-- Identyfikacja projektu -->
    <groupId>org.code-house.cxf</groupId>
    <artifactId>parent</artifactId>
    <name>Code House.Org - CXF</name>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <description>Rodzic projektu, zawiera wszystkie moduly.</description>

    <!-- Składowe projektu -->
    <modules>
        <module>cxf-client</module>
        <module>cxf-contract</module>
        <module>cxf-server</module>
        <module>cxf-webapp</module>
    </modules>

    <!-- Definicje zmiennych dostępne również w modułach -->
    <properties>
        <code-house.cxf.version>2.1.1</code-house.cxf.version>
        <code-house.jaxb.version>2.1.3</code-house.jaxb.version>
        <code-house.spring.version>2.5.4</code-house.spring.version>
    </properties>

    <build>
        <plugins>
            <!-- Konfiguracja kompilatora -->
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.5</source>
                    <target>1.5</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <reporting>
    <!--Wycięte :) -->
    </reporting>

    <!-- Predefiniowane wersje bibliotek -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.apache.cxf</groupId>
                <artifactId>cxf-rt-frontend-jaxws</artifactId>
                <version>${code-house.cxf.version}</version>
            </dependency>
            <dependency>
                <groupId>org.apache.cxf</groupId>
                <artifactId>cxf-rt-transports-http</artifactId>
                <version>${code-house.cxf.version}</version>
            </dependency>
            <dependency>
                <groupId>org.apache.cxf</groupId>
                <artifactId>cxf-rt-transports-http-jetty</artifactId>
                <version>${code-house.cxf.version}</version>
            </dependency>
            <dependency>
                <groupId>com.sun.xml.bind</groupId>
                <artifactId>jaxb-impl</artifactId>
                <version>${code-house.jaxb.version}</version>
            </dependency>
            <dependency>
                <groupId>javax.xml.bind</groupId>
                <artifactId>jaxb-api</artifactId>
                <version>2.1</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

</project>

Contract

Zgodnie z tym, co napisałem wcześniej - przyjąłem podejście, że WSDL jest pisany ręcznie, głównie dlatego że dla większych projektów można w prosty sposób narzucić jakąś organizację i podział plików, z których są następnie generowane źródła.
Najistotniejsza wstawka, która powinna znaleźć się w pomie:

<!-- Generowanie kodu z deskryptora WSDL -->
<plugin>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-codegen-plugin</artifactId>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <configuration>
                <sourceRoot>${basedir}/target/jaxws</sourceRoot>
                <wsdlOptions>
                    <wsdlOption>
                        <wsdl>
                            ${basedir}/src/main/resources/maven.wsdl
                        </wsdl>
                        <extraargs>
                            <extraarg>-quiet</extraarg>
                        </extraargs>
                    </wsdlOption>
                </wsdlOptions>
            </configuration>
            <goals>
                <goal>wsdl2java</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Po dodaniu tej wstawki do sekcji build/plugins możemy przejść do tworzenia deskryptora usługi. W moim przypadku przyjąłem następujący podział:

1. maven.wsdl - definicje metod oraz komunikatów w rozumieniu WSDL (messages). Można z powodzeniem wyłączyć z tego pliku same koperty i pozostawić metody a to co potrzebne włączyć dyrektywą wsdl:import.
2. types.xsd - typy używane do komunikacji - zazwyczaj pary request+response używane bezpośrednio w definiowaniu elementów wsdl:part.
3. definition.xsd - definicje typów złożonych, niezależnych od usług, tj. opis domain-modelu z którym usługa pracuje.

Każdy z tych plików ma inną przestrzeń nazw.

maven.wsdl

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://code-house.org/services/maven"
    xmlns:types="http://code-house.org/services/maven/types"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://code-house.org/services/maven"
    name="MavenServices"
    >

    <wsdl:types>
        <xsd:schema targetNamespace="http://code-house.org/services/maven/types">
            <xsd:include schemaLocation="types.xsd" />
        </xsd:schema>
    </wsdl:types>

    <wsdl:message name="findArtifactRequest">
        <wsdl:part name="request" type="types:FindArtifactRequest" />
    </wsdl:message>
    <wsdl:message name="findArtifactResponse">
        <wsdl:part name="response" type="types:FindArtifactRespose" />
    </wsdl:message>

    <wsdl:portType name="MavenArtifactType">
        <wsdl:operation name="findArtifact">
            <wsdl:input message="tns:findArtifactRequest" />
            <wsdl:output message="tns:findArtifactResponse" />
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="MavenArtifactSOAP" type="tns:MavenArtifactType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="findArtifact">
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="MavenServices">
        <wsdl:port binding="tns:MavenArtifactSOAP" name="Maven Services">
            <soap:address location="http://localhost:8080/webapp/services/maven" />
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

types.xsd

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://code-house.org/services/maven/types"
    xmlns:tns="http://code-house.org/services/maven/types"
    xmlns:def="http://code-house.org/services/maven/definition"
    elementFormDefault="qualified">

    <import schemaLocation="definition.xsd"
        namespace="http://code-house.org/services/maven/definition" />

    <complexType name="FindArtifactRequest">
        <sequence>
            <element name="query" type="def:ArtifactInfo" />
        </sequence>
    </complexType>

    <complexType name="FindArtifactRespose">
        <sequence>
            <element name="downloadURL" type="anyURI" />
        </sequence>
    </complexType>

</schema>

definition.xsd

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://code-house.org/services/maven/definition"
    xmlns:tns="http://code-house.org/services/maven/definition"
    elementFormDefault="qualified">

    <complexType name="ArtifactInfo">
        <sequence>
            <element name="groupId" type="string" />
            <element name="artifactId" type="string" />
            <element name="version" type="string" minOccurs="0" />
            <element name="classifier" type="tns:Classifier" minOccurs="0" />
            <element name="packaging" type="tns:Packaging" minOccurs="0" />
            <element name="type" type="tns:Type" minOccurs="0" />
        </sequence>
    </complexType>

    <simpleType name="Type">
        <restriction base="string">
            <enumeration value="dll" />
            <enumeration value="so" />
        </restriction>
    </simpleType>

    <simpleType name="Classifier">
        <restriction base="string">
            <enumeration value="sources" />
            <enumeration value="javadoc" />
            <enumeration value="resources" />
        </restriction>
    </simpleType>

    <simpleType name="Packaging">
        <restriction base="string">
            <enumeration value="pom" />
            <enumeration value="jar" />
            <enumeration value="war" />
            <enumeration value="bundle" />
        </restriction>
    </simpleType>

</schema>

Po odpaleniu polecenia mvn:install powinniśmy otrzymać w konsoli fragment podobny do tego:

[INFO] [cxf-codegen:wsdl2java {execution: default}]

Jest to informacja, że plugin CXF został poprawnie skonfigurowany i uruchomiony.

Serwer

Sercem naszej usługi jest oczywiście jej implementacja dlatego też nie możemy obejść się bez niej. :) Projekt ten ma tylko dwie zależności - contract oraz artefakt cxf-rt-frontend-jaxws.

Konfiguracja serwera odbywa się w oparciu o springa:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:jaxws="http://cxf.apache.org/jaxws"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://cxf.apache.org/jaxws

http://cxf.apache.org/schemas/jaxws.xsd

    ">

    <!-- Dodatkowy bean zawierający właściwą implementację logiki związanej z wyszukiwaniem -->
    <bean id="service" class="org.code_house.services.maven.DummyMavenSearchServiceImpl" />

    <!-- Bean będący implementacją usługi jako takiej - obsługujący wejście/wyjście -->
    <bean id="mavenService" class="org.code_house.services.maven.MavenArtifactTypeImpl">
        <property name="service" ref="service" />
    </bean>

    <!-- Konfiguracja endpointu CXFa -->
    <jaxws:endpoint address="maven" id="jaxwsMavenService" implementor="#mavenService" />

</beans>

Serwer zawiera w zasadzie niewiele kodu, oto i on:

package org.code_house.services.maven;

import java.net.URISyntaxException;

import javax.jws.WebService;

import org.code_house.services.maven.definition.ArtifactInfo;
import org.code_house.services.maven.types.FindArtifactRequest;
import org.code_house.services.maven.types.FindArtifactRespose;

/**
  * Implementacja usługi.
  */
@WebService(serviceName = "MavenService",
    endpointInterface = "org.code_house.services.maven.MavenArtifactType",
    targetNamespace = "http://code-house.org/services/maven"
)
public class MavenArtifactTypeImpl implements MavenArtifactType {

    /**
      * Bean zawierający implementację logiki biznesowej.
      */
    private MavenSearchService service;

    public FindArtifactRespose findArtifact(FindArtifactRequest request) {
        ArtifactInfo info = request.getQuery(); // pobranie struktury przekazanej od klienta

        // sformuowanie odpowiedzi
        FindArtifactRespose response = new FindArtifactRespose();
        try {
            response.setDownloadURL(service.find(info).toURI().toString());
        } catch (URISyntaxException e) {
            throw new RuntimeException(e);
        }
        return response;
    }

    /**
     * Ustawienie wartości pola service.
     *
     * @param service Nowa wartość pola service.
     */
    public void setService(MavenSearchService service) {
        this.service = service;
    }
}

Dodatkowy kod, który nie jest konieczny do implementacji usługi to definicja interfejsu MavenSearchService. Dzięki zastosowaniu takiego rozwiązania można w prostszy sposób testować działanie usługi poprzez przekazywanie jej mocka stworzonego np. przy pomocy easy mocka. Kod takiego testu pominąłem ze względu na to, że notka i tak już jest za długa w tym momencie a jesteśmy ledwo w połowie drogi. :)

Przykładowa implementacja wcześniej wspomnianego intefejsu nie zawiera żadnej logiki i zawsze zwraca tą samą wartość.

package org.code_house.services.maven;

import java.net.MalformedURLException;
import java.net.URL;

import org.code_house.services.maven.definition.ArtifactInfo;

// Najprostsza implementacja tylko po to żeby sprawdzić działanie usługi
public class DummyMavenSearchServiceImpl implements MavenSearchService {

    public URL find(ArtifactInfo info) {
        try {
            return new URL("http://repo1.maven.org/maven2/org/apache/apache/4/apache-4.pom");
        } catch (MalformedURLException e) {
            throw new RuntimeException(e);
        }
    }

}

Zanim odpalimy serwer konieczna będzie jeszcze jedna rzecz - konfiguracja transporu, w naszym przypadku servletu CXF.

Webapp

Webapp posiada bezpośrednie zależności do 2 artefaktów CXFa: cxf-rt-transports-http oraz cxf-rt-bindings-http. Druga jest opcjonalna, bez niej CXF nie będzie wyświetlał dostępnych usług w postaci tabelki html.

Przydatna może być wtyczka jetty (sekcja build/plugins), która pozwala na uruchomienie aplikacji bez konieczności instalowania kontenera servletów:

<plugin>
    <groupId>org.mortbay.jetty</groupId>
    <artifactId>maven-jetty-plugin</artifactId>
    <version>6.1.11</version>
    <configuration>
        <scanIntervalSeconds>10</scanIntervalSeconds>
        <connectors>
            <connector implementation="org.mortbay.jetty.nio.SelectChannelConnector">
                <port>8080</port>
                <maxIdleTime>60000</maxIdleTime>
            </connector>
        </connectors>
    </configuration>
</plugin>

Ostatnia zależność odnosi się do implementacji usługi - czyli naszego artefaktu server. Najistotniejsze elementy konfiguracji webappa to web.xml oraz cxf-beans.xml.

web.xml

Warto zauważyć w poniższym listingu fajną możliwość, którą daje nam Spring w postaci wildcardów określających położenie konfiguracji - w tym przypadku classpath:/module/*-context.xml. Oznacza to, że Spring przeskanuje wszystkie biblioteki od których zależy projekt i dołączy ich konfigurację do głownej, dzięki czemu będziemy mogli uzyskać bardziej modułową i elastyczną budowę aplikacji. Może Dynamic Modules to nie jest ale na codzień w zupełności wystarcza :).

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="ocs" version="2.5"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    xsi:schemaLocation="

http://java.sun.com/xml/ns/javaee

        http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    >

    <!-- Informacje nazewnicze dla kontenera -->
    <display-name>Maven Search Services :: Webapp</display-name>
    <description>Frontend indeksera.</description>

    <!-- Lokalizacje plików konfiguracyjnych -->
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>
            <!-- Konfiguracja zabezpieczeń opartych o spring secuirty -->
            /WEB-INF/security.xml
            <!-- Konfiguracja CXF -->
            /WEB-INF/cxf-beans.xml
            <!-- Konfiguracja kontekstu -->
            /WEB-INF/applicationContext.xml
            <!-- Wczytanie konfiguracji modułów -->
            classpath:/module/*-context.xml
        </param-value>
    </context-param>

    <!-- Servlet obsługujący usługi sieciowe -->
    <servlet>
        <servlet-name>CXFServlet</servlet-name>
        <servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!-- Mapowanie adresu usług sieciowych -->
    <servlet-mapping>
        <servlet-name>CXFServlet</servlet-name>
        <url-pattern>/services/*</url-pattern>
    </servlet-mapping>

    <!-- Inicjowanie kontekstu springa -->
    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

</web-app>

cxf-beans.xml

Plik ten zawiera definicje konfiguracyjne CXFa. W poniższej formie włączana jest tylko część modułów CXF w celu zmniejszenia użycia zasobów.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:cxf="http://cxf.apache.org/core"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="

http://cxf.apache.org/core

http://cxf.apache.org/schemas/core.xsd

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

    ">

    <!-- Moduły CXF-a -->
    <import resource="classpath:META-INF/cxf/cxf.xml"/>
    <import resource="classpath:META-INF/cxf/cxf-extension-soap.xml"/>
    <import resource="classpath:META-INF/cxf/cxf-extension-http-binding.xml"/>
    <import resource="classpath:META-INF/cxf/cxf-servlet.xml"/>

</beans>

Pozostałe pliki konfiguracyjne są praktycznie puste, ponieważ tyczą się obszarów niezwiązanych z tematem tego wpisu. Po tym wszystkim możemy uruchomić naszą aplikację poleceniem mvn jetty:run. Po wejściu na adres http://localhost:8080/webapp/services naszym oczom powinna ukazać się lista podobna do poniższej:

Nie wiem niestety dlaczego CXF generuje zły adres usługi (pomijający mapowanie servletu) oraz ma problemy z wystawieniem WSDLa. Jakkolwiek i bez tego wszystko działa poprawnie - znaczy wywoływanie usług rzecz jasna. :)

W tym momencie możemy uruchomić Soap UI i wykonać jedyną dostępną metodę - findArtifact.

Client

Ostatnim z elementów, który pozostał do omówienia jest klient. Niestety z racji na to, że ta nota już się wystarczająco rozrosła zrobię to w kolejnym wpisie. Mam nadzieję, że nota ta nieco ułatwi przyszłym użytkownikom CXFa jego poznanie. :) Dla tych, którym nie chce się wpisywać tego wszystkiego w edytorze zamieszczam źródła razem z działającym klientem. Projekty nie są nadzwyczajnie dopieszczone, ale w zupełności wystarczą do startu. Znajduje się też tam w pełni działający klient stworzonej usługi. Pozdrawiam i życzę miłej zabawy!

	<!-- Definicja książki -->
	<complextype name="Book">
		<sequence>
			<element name="title" type="string" minOccurs="1" />
			<element name="isbn" type="string" />
			<element name="releaseDate" type="date" />
			<element name="author" type="tns:Author" maxOccurs="unbounded" />
		</sequence>
	</complextype>

Jak widać, każda książka ma określoną datę wydania. Jakkolwiek typ date z XML Schema nie jest bezpośrednio odwzorowany do java.util.Date czy też java.util.Calendar. W przypadku implementacji dostarczonej przez Sun mamy do czynienia z obiektami klasy XMLGregorianCalendarImpl. Rozwiązaniem problemu jest dodanie odpowiedniego adaptera. Możemy robić to ręcznie ale najwygodniejszym rozwiązaniem będzie skorzystanie z gotowca - klasy javax.xml.bind.DatatypeConverter. Jej użycie wygląda następująco:

< ?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://dywicki.pl/court"
    xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="2.0"
    xmlns:tns="http://dywicki.pl/court" elementFormDefault="qualified">
    <annotation>
        <appinfo>
            <jaxb :globalBindings>
                <jaxb :javaType name="java.util.Calendar" xmlType="date"
                    parseMethod="javax.xml.bind.DatatypeConverter.parseDate"
                    printMethod="javax.xml.bind.DatatypeConverter.printDate" />
            </jaxb:globalBindings>
        </appinfo>
    </annotation>

    <!-- tutaj deklaracje typów -->
</schema>

Podobne rozwiązanie można wykorzystać na poziomie pojedyńczego elementu aby zmapować konkretny element do obiektu. Element annotation można również dodać do deklaracji simpleType (powiedzmy reprezentacja numeru pesel + proste restrykcje).

    <complextype name="File">
        <sequence>
            <element name="category" type="string">
                <annotation>
                    <appinfo>
                        <jaxb :javaType
                            name="pl.dywicki.court.Category"
                            parseMethod="pl.dywicki.court.Category.parse"
                            printMethod="pl.dywicki.court.Category.print"
                        />
                    </appinfo>
                </annotation>
            </element>
        </sequence>
    </complextype>

JAXB wygeneruje wówczas odpowiednie adnotacje dla tworzonych klas oraz adaptery, które odwołują się do metod wskazanych w atrybutach elementu javaType.

W moim przypadku kod klasy Category wygląda następująco:

package pl.dywicki.court;

/**
 * Reprezentacja kategorii sprawy.
 *
 * @author Lukasz Dywicki <a href="mailto:luke@code-house.net">luke@code-house.net</a>
 **/
public class Category {

    private String name;

    public Category(String value) {
        this.name = value;
    }

    public static Category parse(String value) {
        return new Category(value);
    }

    public static String print(Category value) {
        return value.name;
    }
}

Jest to oczywiście maksymalnie uproszczony przykład. W konstruktorze bądź metodach, które konwertują string do obiektu możemy podpiąć walidację i bronić się wyjątkami przed nieprawidłowymi wartościami by uniemożliwić deserializację dokumentu.

Mamy już pomysł, teraz zatem kolej na kod. Pluginy są podpinane przez XJC i są odpalane po procesie parsowania schematu XML.
Krok po kroku co należy zrobić.

• Stworzyć klasę rozszerzającą com.sun.tools.xjc.Plugin
• Stworzyć jar, który będzie zawierał plugin (chociażby skryptem ant). Poniższy przykład pakuje wszystko z bin_plugin oraz katalog META-INF.

<project name="plugin" default="jar">
	<target name="jar">
		<delete file="plugin.jar" />
		<jar destfile="plugin.jar">
			<fileset dir="bin_plugin" />
			<fileset file="./*" excludes="*" includes="META-INF/**" />
		</jar>
	</target>
</project>

• W paczce (jar) należy należy stworzyć plik META-INF/services/com.sun.tools.xjc.Plugin
• W pliku tym należy umieścić listę kolejnych pluginów - to znaczy wymienić pełne nazwy klas, po kolei każdą w nowej linii

com.sun.tools.xjc.addon.locator.SourceLocationAddOn
com.sun.tools.xjc.addon.sync.SynchronizedMethodAddOn
com.sun.tools.xjc.addon.at_generated.PluginImpl
pl.dywicki.plugin.PropertyChangePlugin

Mając tak przygotowane archiwum uruchamiamy xjc:

xjc -cp nasz.jar -extension -nasz_plugin schemat.xsd

Kilka słów wyjaśnienia -cp to class path, -extension włącza pluginy, a -nasz_plugin informuje xjc, że chcemy uruchomić plugin, który legitymuje się taką dyrektywą.

Po tych wszystkich karkołomnych zabiegach możemy spokojnie zabrać się za kodowanie..

package pl.dywicki.plugin;

import java.beans.PropertyChangeSupport;

import javax.xml.bind.annotation.XmlTransient;

import org.xml.sax.ErrorHandler;

import com.sun.codemodel.JBlock;
import com.sun.codemodel.JDefinedClass;
import com.sun.codemodel.JExpr;
import com.sun.codemodel.JFieldRef;
import com.sun.codemodel.JFieldVar;
import com.sun.codemodel.JInvocation;
import com.sun.codemodel.JMethod;
import com.sun.codemodel.JMod;
import com.sun.codemodel.JVar;
import com.sun.tools.xjc.Options;
import com.sun.tools.xjc.Plugin;
import com.sun.tools.xjc.outline.ClassOutline;
import com.sun.tools.xjc.outline.Outline;

/**
 * Plugin dorzucający do wygenerowanych klas obsługę powiadamiania o zmianach
 *
 * @author Łukasz Dywicki
 */
public class PropertyChangePlugin extends Plugin {

	@Override
	public String getOptionName() {
		// nasz plugin będzie uruchomiony poprzez dyrektywę -Xlistener
		return "Xlistener";
	}

	@Override
	public String getUsage() {
		// help dla użytkownika
		return "  -Xlistener propagowanie zdarzeń przy pomocy standardów JavaBeans";
	}

	@Override
	public boolean run(Outline outline, Options opt, ErrorHandler errorHandler) {
		// a to jest najważniejsza część pluginu :)

		// przeglądamy wszystkie dostępne klasy
		for (ClassOutline co : outline.getClasses()) {
			// definicja pojedyńczej klasy, przy pomocy JDefinedClass
			// możemy dodawać nowe własności etc
			JDefinedClass clazz = co.implClass;

			addField(clazz);

			changeMethods(clazz);
		}
		return true;
	}

	/**
	 * Dodanie pola do generowanej klasy.
	 *
	 * @param clazz Klasa do której dorzucamy pole
	 */
	private void addField(JDefinedClass clazz) {
		// tworzymy w wygenerowanej klasie pole
		// private PropertyChangeSupport support = new PropertyChangeSupport(this);
		JFieldVar $field = clazz.field(JMod.PRIVATE | JMod.TRANSIENT, PropertyChangeSupport.class, "support");
		// inicjujemy pole
		JInvocation _new = JExpr._new($field.type());
		// dodajemy argument (this)
		_new.arg(JExpr._this());
		$field.init(_new);
		// dodanie adnotacji @XmlTransient do pola, aby nie było ono
		// obsługiwane przez JAXB
		$field.annotate(XmlTransient.class);
	}

	/**
	 * Modyfikacja metod set*..
	 *
	 * @param clazz Klasa którą "przerabiamy".
	 **/
	private void changeMethods(JDefinedClass clazz) {
		for (JMethod method : clazz.methods()) {
			if (method.name().startsWith("set")) {
				String tmp = method.name().substring(3);
				String fieldName = tmp.substring(0, 1).toLowerCase()
					+ tmp.substring(1);
				addSupport(method, fieldName);
			}
		}
	}

	/**
	 * Zmodyfikowanie istniejących metod.
	 *
	 * @param method Obiekt metody
	 * @param fieldName Nazwa pola, które metoda obsługuje
	 */
	private void addSupport(JMethod method, String fieldName) {
		// przeskakujemy do pierwszej linijki w metodzie
		JBlock body = method.body();
		body.pos(0);
		// odwoładnie do np this.userName
		JFieldRef ref = JExpr.ref(fieldName);
		// deklaracja zmiennej o typie pierwszego argumentu i nazwie temp
		JVar $temp = body.decl(method.listParams()[0].type(), "temp");
		// przypisanie do zmiennej temp wartości pola
		$temp.init(JExpr.ref(fieldName));

		// przeskoczenie na koniec metody
		body.pos(body.getContents().size());

		// odwołanie do pola this.support (stworzone w metodzie addField) i
		// wywołanie metody this.support.firePropertyChange()
		JInvocation invocation = JExpr.ref("support").invoke("firePropertyChange");
		// kolejne argumenty metody - nazwa property, stara wartość i nowa wartość
		invocation.arg(fieldName);
		invocation.arg($temp);
		invocation.arg(ref);

		// dorzucenie wywołania na końcu metody
		body.add(invocation);
	}

}

Kosztuje to troszkę pracy, ale koniec końców mamy wsparcie dla obsługi zdarzeń. Dla zainteresowanych dołączam jeszcze dwa pluginy - generujące metody hashCode i equals. Napisałem je, gdy nie miałem dostępu do internetu, jeśli chcecie ich używać - zalecam wcześniej wspomniane jaxb-commons.

Na końcu chciałem wspomnieć o tym że i ja miałem swój udział na WarsJavie prowadząc warsztat na temat JAXB. Prawdę powiedziawszy czułem się nieco przerażony - wszyscy podjęli się poważnych tematów, Spring, OSGi, JRuby, JMS podczas gdy ja miałem powiedzieć o bibliotece do robienia obiektów z XMLa i XMLa z obiektów. Szczerze powiedziawszy miałem również spore obawy czy treść, którą przygotowałem będzie w stanie zapełnić półtorej godziny, jakie dostałem na prezentację tematu. Postanowiłem więc dokładnie napisać co jest do zrobienia, dopieścić przykłady, wynikiem czego kładłem się spać o 3 w nocy. Węsząc problemy zawczasu spakowałem laptopa, jak się okazało słusznie - obudziłem się na tyle prędko, że zdążyłem wciągnąć spodnie, wybiec na tramwaj.. Gdy dotarłem na miejsce była już 9:10, dosłownie pięć minut przed rozpoczęciem. Byłaby niezła wpadka gdyby zwiał mi tramwaj i musiałbym czekać 10 minut na kolejny. Szczęście - udało się dotrzeć. Na początku drobne problemy z rzutnikiem, następnie z konfiguracją rozdzielczości.. i tym sposobem uleciało dobre 15 minut.
Parę slajdów, które miałem przygotowane minęło stanowczo zbyt szybko i musiałem siadać do klawiatury. Dziwna rzecz, kiedy człowiek siada, używa tylko dłoni, a mimo wszystko język ma zaplątany. :) Zaiste, problematyczne było pisanie i mówienie. Właściwie to więcej pisałem jak mówiłem. Czas zleciał bardzo szybko, zdążyłem w zasadzie omówić 2 aspekty, na które się gotowałem czyli użycie adnotacji i generowanie kodu ze schematu XSD jak i jeden na który się nie przygotowywałem - radzenie sobie z wyjątkami ;). Nie zdążyłem nic powiedzieć na temat wpływania na zachowanie kompilatora schemy (xjc) poprzez tworzenie plików xjb oraz pisania własnych pluginów. Te punkty staną się najprawdopodobniej tematem przyszłych not.
Szczerze byłem również bardzo mile zaskoczony tym, że ktoś poprosił o kod po prezentacji. :)

Na grupie pojawił się wątek z opiniami po warsztatach. Niestety nie byłem na Javarsovii i nie mam punktu odniesienia "co było lepsze". Jakkolwiek zdaje mi się, że tradycyjne prezentacje, gdzie jest kilkanaście slajdów i odrobina kodu zdaje się lepsze. Daje dosyć ogólny pogląd na więcej aspektów niż powstający kod. Z drugiej jednak strony forma warsztatu jest bardziej efektowna, co można było bez wątpienia zaobserwować w przypadku JRuby. Z resztą sama dyskusja tuż po prezentacji Wiktora mogła pokazać jak wiele emocji budzi owe novum. :)

Dla zainteresowanych - zamieściłem źródła wszystkich projektów jakie realizowałem przed i w trakcie prezentacji oraz filmik "z kodowania" (nagrany w Cam Studio). Ostrzegam, że avik jest słabo skompresowany i po wypakowaniu zajmuje 670MB!

Przykładowy skrypt PHP, który uzyskuje informacje o konfiguracji Agavi:

A teraz część wyniku, który PHP wyświetla w konsoli:

Teraz kod Javy, który odczytuje sobie informacje.. (nawiasy kwadratowe przy listach podyktowane błędami w skrypcie, który koloruje składnię)

		// odpalamy interpreter PHP
		Runtime runtime = Runtime.getRuntime();
		Process exec = runtime.exec("php -q E:/agavi-ide/org.codehouse.bridge/src/org/codehouse/bridge/test2.php");

		// podnosimy kontekst JAXB
		JAXBContext context = JAXBContext.newInstance(ObjectFactory.class);
		// deserializujemy XML wygenerowany przez PHP
		WddxPacket object = (WddxPacket) context.createUnmarshaller().unmarshal(exec.getInputStream());

		// odczytujemy informacje
		for (Object stc : object.getData().getWDDXData()) {
			// spodziewamy się informacji o typie złożonym
			if (stc instanceof Struct) {
				List[generated.Var] vara = ((Struct) stc).getVar();
				for (Var value : vara) {
					// pozostaje nam tylko odczytanie zserializowanej wartości
					List[Object] configurationValue = value.getWDDXData();
					System.out.println(value.getName() + ": " + ((generated.String) configurationValue.get(0)).getvalue());
				}
			}
		}

Wynik działania poniższego kodu to:

Czyli wszystko czego trzeba było nam do szczęścia! :)

Pora na przykład bardziej złożony, wyciągnięcie informacji o jakiejś klasie widoku użytej w aplikacji opartej o Agavi.

Drobna przeróbka kodu Javy, który był użyty wcześniej i wynikiem jest

Tym, którzy dobrnęli do końca tej noty dziękuję za wytrwałość. :) Kolejna nota będzie być może o tym jak wywoływać metody statyczne klas Javy z poziomu XSLT (wierzcie mi, da się!).

Czas jakiś temu udało mi się stworzyć pierwszy działający edytor w oparciu o Eclipse.
Kilka informacji co pod spodem:

• SharedHeaderFormEditor - ładny tekstowy nagłówek oraz możliwość dodawania zakładek
• FormPage i FormToolkit - użyte do stworzenia układu, który widać na załączonym obrazku
• JFace Databinding - zapewnia propagowanie zmian z formularza do obiektów
• JAXB 2 - mapowanie plików XML do odpowiednich klas
• JFace - table viewer i parę innych dodatków

Całość ogólnie jest prosta niczym konstrukcja cepa, w działaniu sprawia się dobrze. Jak tylko ogarnę kod postaram się opisać krok po kroku jak można coś podobnego stworzyć na własny użytek.

Splatch wraca do gry i będzie grać wysoko! ;-)

Ogólniki

JAXB ma za zadanie ułatwić pracę z XML poprzez automatyczne dostarczanie obiektów zamiast żmudnego, ręcznego obrabiania plików SAX, DOM czy StAX. Jest to dodatkowa warstwa zbudowana na bazie Java Api for XML Processing
. Druga wersja JAXB jest dołączona do J2SE 1.6.

Spójrzmy teraz na schemat budowy JAXB:

1. Kompilator
   1. Schema - dokument opisujący strukturę dokumentu - może to być XML Schema, DTD jak również Relax NG czy też WSDL.
   2. XML /Java Binding Customization - JAXB daje nam możliwość wpływania na wygenerowany kod poprzez ten właśnie mechanizm, dzięki temu można określić np. metody, które będą tworzyć elementy w przypadku odczytu z dokumentu bądź serializować w przypadku zapisu.
2. Runtime
   1. Portable JAXB-annotated classes - kod, który wygenerowaliśmy przy użyciu kompilatora bądź klasy, do których dodaliśmy adnotacje.
   2. Object Factory - klasa, która tworzy obiektowe reprezentacje naszych elementów XML.
   3. Binding runtime framework implementation - obsługuje proces odczytu danych (unmarshalling) oraz ich zapisu (marshalling), obsługuje również walidację. Element ten do poprawnego działania wymaga elementów wymienionych powyżej - czyli klas z adnotacjami oraz ich "fabryki".

Pierwszy projekt

Pamiętam, że kiedyś chciałem stworzyć prostą aplikację w której mógłbym notować jakie książki mam i komu je wypożyczyłem. Niestety w którymś momencie zabrakło chyba sił i poza definicją struktury dokumentu stworzyłem tyko kilka linii kodu. Nie mniej, po drobnych przeróbkach udało się doprowadzić schemat do porządku. W aplikacji będą występować następujące instancje klas:

1. Books - repozytorium książek, zawiera listę książek
2. Book - definicja książki - atrybuty to title, isbn oraz lista autorów
3. Author - reprezentacja autora - atrybuty firstName, lastName. Dodatkowo opcjonalny jest type wskazujący czy mamy do czynienia z tłumaczem czy też z "normalnym" autorem.
4. AuthorType - typ wyliczeniowy - dostępne wartości to Translator, Author

Aby korzystało się nam z kompilatora (xjc) wygodniej podepniemy go pod Eclipse jako narzędzie zewnętrzne. Tu przyda się kilka informacji na temat samego kompilatora:
xjc [-options ...] file/URL/dir ... [-b bindinfo] ...
Gdzie najważniejsze opcje to:

1. -d, katalog do którego trafi wygenerowany kod
2. -b, dodatkowe mappingi umożliwiające zmianę zachowania kompilatora
3. -p, paczka do której trafi wygenerowany kod
4. -classpath, miejsca w których xjc ma szukać klas, które zostały użyte w mappingach

Przykładowo

xjc -d generated schema.xsd

Spowoduje, że klasy wylądują w katalogu generated. Nazwa paczki zostanie zaczerpnięta z atrybutu targetNamespace dokumentu zawartego w schemacie. Obok znajduje się screen z konfiguracją - z ważniejszych informacji - Working directory ustawione na ${project_loc} pozwala nam się nawigować po katalogach względem aktualnie zaznaczonego w nawigatorze projektu. wartość w polu Arguments -d generated ${resource_loc} -verbose -extension -npa oznacza, że wygenerowane klasy wylądują w katalogu "generated" (należy stworzyć taki source folder). Zmienna ${resource_loc} pozwala nam użyć aktualnie zaznaczonego pliku w nawigatorze. Dzięki takiej konfiguracji niezależnie od projektu i pliku jesteśmy w stanie wygenerować potrzebne nam klasy poprzez dwa kliknięcia - pierwsze w nawigatorze, drugie na ikonie external tools.

Schemat jest dostępny do ściągnięcia, podobnie jak przykładowy plik z danymi. Proszę zwrócić uwagę na to jak jest zdefiniowany główny element dokumentu - poprzez zawarcie typu anonimowego. Jeśli zdefiniujemy oddzielnie element i typ to wówczas konieczne będzie ręczne dodanie adnotacji @XmlRootElement przy klasie Books. O tym dlaczego JAXB się tak zachowuje można wyczytać na jednym z Sun-owskich blogów.

package pl.dywicki.books.app;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.Marshaller;

import pl.dywicki.books.Author;
import pl.dywicki.books.AuthorType;
import pl.dywicki.books.Book;
import pl.dywicki.books.Books;
import pl.dywicki.books.ObjectFactory;

/**
 * Testowa klasa pokazująca użycie JAXB do zapisywania danych.
 *
 * @author Łukasz Dywicki
 */
public class App {

	public static void main(String[] args) throws Exception {

		// repozytorium książek
		Books books = new Books();

		// przykładowa książka
		Book book = new Book();
		book.setTitle("Test title");
		book.setIsbn("111-111-111");

		// testowy autor
		Author author = new Author();
		author.setFirstName("Martin");
		author.setLastName("Fowler");
		book.getAuthor().add(author);

		// testowy tłumacz
		author = new Author();
		author.setFirstName("Łukasz");
		author.setLastName("Dywicki");
		author.setType(AuthorType.TRANSLATOR);
		book.getAuthor().add(author);

		// dodanie książki do repozytorium
		books.getBook().add(book);

		JAXBContext context = JAXBContext.newInstance(ObjectFactory.class);
		Marshaller marshaller = context.createMarshaller();
		// chcemy ładnych wcięć w wyniku! :)
		marshaller.setProperty("jaxb.formatted.output", true);
		marshaller.marshal(books, System.out);
	}

}

Po uruchomieniu tego przykładu w konsoli powinien pokazać się taki oto wynik:

< ?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2_books xmlns:ns2="http://dywicki.pl/books">
    <book>
        <title>Test title</title>
        <isbn>111-111-111</isbn>
        <author>
            <firstname>Martin</firstname>
            <lastname>Fowler</lastname>
        </author>
        <author>
            <firstname>Łukasz</firstname>
            <lastname>Dywicki</lastname>
            <type>Translator</type>
        </author>
    </book>
</ns2_books>

(Zamiast ns2_books powinno być ns2:books, ale narzędzie kolorujące składnie sobie nie radzi).

Dla zainteresowanych załączam źródła projektu.