Введение в Apache CXF

1. Обзор

Apache CXF — это полностью совместимая среда JAX-WS.

Помимо функций, определенных стандартами JAX-WS, Apache CXF обеспечивает возможность преобразования между классами WSDL и Java, API-интерфейсы, используемые для управления необработанными XML-сообщениями, поддержку JAX-RS, интеграцию с Spring Framework и т. д.

Это руководство является первым из серии, посвященной Apache CXF, в которой представлены основные характеристики платформы. Он использует только стандартные API-интерфейсы JAX-WS в исходном коде, но все еще использует преимущества Apache CXF за кулисами, такие как автоматически генерируемые метаданные WSDL и конфигурация CXF по умолчанию.

2. Зависимости Maven

Ключевой зависимостью, необходимой для использования Apache CXF, является org.apache.cxf: cxf — rt — frontend — jaxws . Это обеспечивает реализацию JAX-WS для замены встроенной JDK:

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-frontend-jaxws</artifactId>
    <version>3.1.6</version>
</dependency>

Обратите внимание, что этот артефакт содержит файл с именем javax.xml.ws.spi.Provider внутри каталога META-INF/services . Java VM просматривает первую строку этого файла, чтобы определить, какую реализацию JAX-WS следует использовать. В этом случае содержание строки — org.apache.cxf.jaxws.spi.ProviderImpl , относящееся к реализации, предоставляемой Apache CXF.

В этом руководстве мы не используем контейнер сервлетов для публикации службы, поэтому для предоставления необходимых определений типов Java требуется другая зависимость:

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-transports-http-jetty</artifactId>
    <version>3.1.6</version>
</dependency>

Последние версии этих зависимостей см. в cxf-rt-frontend-jaxws и cxf-rt-transports-http-jetty в центральном репозитории Maven.

3. Конечная точка веб-службы

Начнем с класса реализации, используемого для настройки конечной точки службы:

@WebService(endpointInterface = "com.foreach.cxf.introduction.ForEach")
public class ForEachImpl implements ForEach {
    private Map<Integer, Student> students 
      = new LinkedHashMap<Integer, Student>();

    public String hello(String name) {
        return "Hello " + name;
    }

    public String helloStudent(Student student) {
        students.put(students.size() + 1, student);
        return "Hello " + student.getName();
    }

    public Map<Integer, Student> getStudents() {
        return students;
    }
}

Самое важное, на что здесь следует обратить внимание, — это наличие атрибута endpointInterface в аннотации @WebService . Этот атрибут указывает на интерфейс, определяющий абстрактный контракт для веб-службы.

Все сигнатуры методов, объявленные в интерфейсе конечной точки, должны быть реализованы, но не обязательно для реализации интерфейса.

Здесь класс реализации ForEachImpl по- прежнему реализует следующий интерфейс конечной точки, чтобы было ясно, что все объявленные методы интерфейса реализованы, но делать это необязательно:

@WebService
public interface ForEach {
    public String hello(String name);

    public String helloStudent(Student student);

    @XmlJavaTypeAdapter(StudentMapAdapter.class)
    public Map<Integer, Student> getStudents();
}

По умолчанию Apache CXF использует JAXB в качестве архитектуры привязки данных. Однако, поскольку JAXB напрямую не поддерживает привязку Map , которая возвращается из метода getStudents , нам нужен адаптер для преобразования Map в класс Java, который может использовать JAXB .

Кроме того, чтобы отделить элементы контракта от их реализации, мы определяем Student как интерфейс, а JAXB также напрямую не поддерживает интерфейсы, поэтому нам нужен еще один адаптер, чтобы справиться с этим. Фактически, для удобства мы можем объявить Student как класс. Использование этого типа в качестве интерфейса — еще одна демонстрация использования классов адаптации.

Адаптеры демонстрируются в разделе справа ниже.

4. Пользовательские адаптеры

В этом разделе показано, как использовать классы адаптации для поддержки связывания интерфейса Java и Карты с использованием JAXB.

4.1. Адаптер интерфейса

Вот как определяется интерфейс Student :

@XmlJavaTypeAdapter(StudentAdapter.class)
public interface Student {
    public String getName();
}

Этот интерфейс объявляет только один метод, возвращающий строку , и указывает StudentAdapter в качестве класса адаптации для сопоставления себя с типом, который может применять привязку JAXB, и из него.

Класс StudentAdapter определяется следующим образом:

public class StudentAdapter extends XmlAdapter<StudentImpl, Student> {
    public StudentImpl marshal(Student student) throws Exception {
        if (student instanceof StudentImpl) {
            return (StudentImpl) student;
        }
        return new StudentImpl(student.getName());
    }

    public Student unmarshal(StudentImpl student) throws Exception {
        return student;
    }
}

Класс адаптации должен реализовать интерфейс XmlAdapter и предоставить реализацию для методов маршалинга и демаршалирования . Метод маршала преобразует связанный тип ( Student , интерфейс, который JAXB не может напрямую обрабатывать) в тип значения ( StudentImpl , конкретный класс, который может обрабатываться JAXB). Немаршальский метод делает все наоборот .

Вот определение класса StudentImpl :

@XmlType(name = "Student")
public class StudentImpl implements Student {
    private String name;

    // constructors, getter and setter
}

4.2. Адаптер карты

Метод getStudents интерфейса конечной точки ForEach возвращает карту и указывает класс адаптации для преобразования карты в тип, который может обрабатываться JAXB. Подобно классу StudentAdapter , этот класс адаптации должен реализовывать методы маршалинга и демаршалирования интерфейса XmlAdapter : ``

public class StudentMapAdapter 
  extends XmlAdapter<StudentMap, Map<Integer, Student>> {
    public StudentMap marshal(Map<Integer, Student> boundMap) throws Exception {
        StudentMap valueMap = new StudentMap();
        for (Map.Entry<Integer, Student> boundEntry : boundMap.entrySet()) {
            StudentMap.StudentEntry valueEntry  = new StudentMap.StudentEntry();
            valueEntry.setStudent(boundEntry.getValue());
            valueEntry.setId(boundEntry.getKey());
            valueMap.getEntries().add(valueEntry);
        }
        return valueMap;
    }

    public Map<Integer, Student> unmarshal(StudentMap valueMap) throws Exception {
        Map<Integer, Student> boundMap = new LinkedHashMap<Integer, Student>();
        for (StudentMap.StudentEntry studentEntry : valueMap.getEntries()) {
            boundMap.put(studentEntry.getId(), studentEntry.getStudent());
        }
        return boundMap;
    }
}

Класс StudentMapAdapter сопоставляет Map<Integer, Student> с типом значения StudentMap и из него с помощью следующего определения:

@XmlType(name = "StudentMap")
public class StudentMap {
    private List<StudentEntry> entries = new ArrayList<StudentEntry>();

    @XmlElement(nillable = false, name = "entry")
    public List<StudentEntry> getEntries() {
        return entries;
    }

    @XmlType(name = "StudentEntry")
    public static class StudentEntry {
        private Integer id;
        private Student student;

        // getters and setters
    }
}

5. Развертывание

5.1. Определение сервера

Чтобы развернуть веб-службу, описанную выше, мы будем использовать стандартные API-интерфейсы JAX-WS. Поскольку мы используем Apache CXF, платформа выполняет дополнительную работу, например, создает и публикует схему WSDL. Вот как определяется сервисный сервер:

public class Server {
    public static void main(String args[]) throws InterruptedException {
        ForEachImpl implementor = new ForEachImpl();
        String address = "http://localhost:8080/foreach";
        Endpoint.publish(address, implementor);
        Thread.sleep(60 * 1000);        
        System.exit(0);
    }
}

После того как сервер поработает какое-то время для облегчения тестирования, его следует выключить, чтобы высвободить системные ресурсы. Вы можете указать любую продолжительность работы сервера в зависимости от ваших потребностей, передав длинный аргумент методу Thread.sleep .

5.2. Развертывание сервера

В этом руководстве мы используем подключаемый модуль org.codehaus.mojo: exec -maven- plugin для создания экземпляра сервера, показанного выше, и управления его жизненным циклом. Это объявлено в файле Maven POM следующим образом:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <configuration>
        <mainClass>com.foreach.cxf.introduction.Server</mainClass>
    </configuration>
</plugin>

Конфигурация mainClass относится к классу Server , в котором публикуется конечная точка веб-службы. После запуска цели java этого плагина мы можем проверить схему WSDL, автоматически сгенерированную Apache CXF, перейдя по URL-адресу http://localhost:8080/foreach?wsdl .

6. Тестовые случаи

В этом разделе описаны шаги по написанию тестовых случаев, используемых для проверки веб-службы, которую мы создали ранее.

Обратите внимание, что нам нужно выполнить цель exec:java , чтобы запустить сервер веб-службы перед запуском любого теста.

6.1. Подготовка

Первый шаг — объявить несколько полей для тестового класса:

public class StudentTest {
    private static QName SERVICE_NAME 
      = new QName("http://introduction.cxf.foreach.com/", "ForEach");
    private static QName PORT_NAME 
      = new QName("http://introduction.cxf.foreach.com/", "ForEachPort");

    private Service service;
    private ForEach foreachProxy;
    private ForEachImpl foreachImpl;

    // other declarations
}

Следующий блок инициализатора используется для инициализации поля службы типа javax.xml.ws.Service перед запуском любого теста:

{
    service = Service.create(SERVICE_NAME);
    String endpointAddress = "http://localhost:8080/foreach";
    service.addPort(PORT_NAME, SOAPBinding.SOAP11HTTP_BINDING, endpointAddress);
}

После добавления зависимости JUnit в файл POM мы можем использовать аннотацию @Before , как в фрагменте кода ниже. Этот метод запускается перед каждым тестом для повторного создания полей ForEach :

@Before
public void reinstantiateForEachInstances() {
    foreachImpl = new ForEachImpl();
    foreachProxy = service.getPort(PORT_NAME, ForEach.class);
}

Переменная foreachProxy — это прокси для конечной точки веб-службы, а foreachImpl — это просто простой объект Java. Этот объект используется для сравнения результатов вызовов методов удаленной конечной точки через прокси с вызовами локальных методов.

Обратите внимание, что экземпляр QName идентифицируется двумя частями: URI пространства имен и локальной частью. Если аргумент PORT_NAME типа QName метода Service.getPort опущен, Apache CXF будет считать, что URI пространства имен аргумента — это имя пакета интерфейса конечной точки в обратном порядке, а его локальная часть — это имя интерфейса, к которому добавлен порт . , что совпадает со значением PORT_NAME. Поэтому в этом уроке мы можем опустить этот аргумент.

6.2. Тестовая реализация

Первый тестовый пример, который мы проиллюстрируем в этом подразделе, — это проверка ответа, возвращаемого удаленным вызовом метода hello на конечной точке службы:

@Test
public void whenUsingHelloMethod_thenCorrect() {
    String endpointResponse = foreachProxy.hello("ForEach");
    String localResponse = foreachImpl.hello("ForEach");
    assertEquals(localResponse, endpointResponse);
}

Понятно, что метод удаленной конечной точки возвращает тот же ответ, что и локальный метод, а это означает, что веб-служба работает должным образом.

Следующий тестовый пример демонстрирует использование метода helloStudent :

@Test
public void whenUsingHelloStudentMethod_thenCorrect() {
    Student student = new StudentImpl("John Doe");
    String endpointResponse = foreachProxy.helloStudent(student);
    String localResponse = foreachImpl.helloStudent(student);
    assertEquals(localResponse, endpointResponse);
}

В этом случае клиент отправляет объект Student конечной точке и получает в ответ сообщение, содержащее имя студента. Как и в предыдущем тестовом примере, ответы как на удаленные, так и на локальные вызовы одинаковы.

Последний тестовый пример, который мы показываем здесь, более сложен. Как определено классом реализации конечной точки службы, каждый раз, когда клиент вызывает метод helloStudent в конечной точке, отправленный объект Student будет сохраняться в кэше. Этот кеш можно получить, вызвав метод getStudents на конечной точке. Следующий тестовый пример подтверждает, что содержимое кэша учащихся представляет собой то, что клиент отправил в веб-службу:

@Test
public void usingGetStudentsMethod_thenCorrect() {
    Student student1 = new StudentImpl("Adam");
    foreachProxy.helloStudent(student1);

    Student student2 = new StudentImpl("Eve");
    foreachProxy.helloStudent(student2);
        
    Map<Integer, Student> students = foreachProxy.getStudents();       
    assertEquals("Adam", students.get(1).getName());
    assertEquals("Eve", students.get(2).getName());
}

7. Заключение

В этом руководстве представлен Apache CXF, мощная платформа для работы с веб-службами на Java. Основное внимание уделялось применению фреймворка в качестве стандартной реализации JAX-WS, но при этом использовались специфические возможности фреймворка во время выполнения.

Реализацию всех этих примеров и фрагментов кода можно найти в проекте на GitHub .