Статьи

Богатый API веб-сервисов для вашей любимой платформы, часть 4: Wicket

Март 14, 2019

Целью этой серии практических рекомендаций является демонстрация разработки API-интерфейса с широкими возможностями веб-служб на различных популярных средах разработки. Часть 4 (это руководство) предназначена для Apache Wicket.

Мы собираемся использовать Enunciate для предоставления богатого API веб-сервиса для знакомого приложения с примерами калитки, включенного в комплект поставки Wicket. Среди примеров Wicket вы найдете приложение «контакты», которое используется для отображения списка контактной информации. Контактные данные предоставляются интерфейсом org.apache.wicket.spring.common.ContactDao . К концу учебника пример приложения будет включать в себя следующее:

  • Конечные точки ОТДЫХА . Контактные конечные точки REST будут предоставлять ресурсы в форматах данных XML и JSON.
  • SOAP конечные точки . API контакта будет представлен через SOAP и определен четко определенным и консолидированным WSDL.
  • Полная документация по API . API веб-службы контактов будет полностью документирован.
  • Код на стороне клиента . Приложение предоставит клиентский код Java, который сможет удаленно обращаться к API веб-службы.

Излагают делает это потрясающе легко развивать этот вид услуг API Web: несколько незначительных настроек в файл сборки, в файле конфигурации, а также некоторые метаданные о интерфейсе сервиса.

Шаг 1: настройка среды

Сначала убедитесь, что у вас установлен Maven , поскольку это инструмент сборки, который мы будем использовать для запуска примера приложения. Затем загрузите дистрибутив Wicket и распакуйте его. Это руководство было написано на основе версии 1.3.4 (последняя стабильная версия на момент написания статьи).

Вы найдете приложение wicket example в каталоге src / jdk-1.5 / wicket-examples распакованного дистрибутива. Мы будем ссылаться на этот каталог как $ EXAMPLES_HOME . Он должен быть готов к развертыванию. Откройте командную консоль в $ EXAMPLES_HOME , затем:


Mvn причал: взорвалась

Вы должны иметь возможность открыть браузер по адресу http: // localhost: 8080 / wicket-examples, чтобы увидеть приложение examples во всей красе. Вы можете увидеть пример контакта, перейдя по адресу http: // localhost: 8080 / wicket-examples / spring .

Далее нам нужно интегрировать Enunciate с нашим проектом. Мы можем сделать это, добавив зависимость от Enunciate в наш файл pom.xml . Также есть несколько версий версий между Enunciate и проектом Wicket, которые должны быть разрешены явным объявлением. Первый — это Spring (обновление до версии 2.5.5), а второй — ASM (обновление до версии 3.1).

pom.xml

<dependencies>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring</artifactId>
    <version>2.5.5</version>
  </dependency>
  <dependency>
    <groupId>asm</groupId>
    <artifactId>asm</artifactId>
    <version>3.1</version>
  </dependency>
  <dependency>
    <groupId>org.codehaus.enunciate</groupId>
    <artifactId>enunciate-rt</artifactId>
    <version>1.8.1</version>
  </dependency>
  ...
</dependencies>

И мы также добавляем maven-enunciate-plugin в список плагинов в нашем файле pom.xml :

pom.xml

...
<plugins>
  ...
  <plugin>
    <groupId>org.codehaus.enunciate</groupId>
    <artifactId>maven-enunciate-plugin</artifactId>
    <version>1.8.1</version>
    <executions>
      <execution>
        <goals>
          <goal>assemble</goal>
        </goals>
      </execution>
    </executions>
  </plugin>
  ...
</plugins>
...
Следует также отметить, что пример контактов используется для демонстрации интеграции Wicket с Spring , но это не имеет отношения к выбору API веб-службы. Пример контактов был выбран, потому что он предоставляет интерфейс службы org.apache.wicket.spring.common.ContactDao , который удобно представить в виде веб-службы. Enunciate использует возможности Spring для развертывания и управления API веб-службы, но это должно быть прозрачным для процесса разработки.

Теперь давайте добавим API веб-сервиса.

Шаг 2: Создайте конфигурацию

Вот файл конфигурации Enunciate, который Enunciate использует для предоставления API веб-службы службе контактов. Удалите это в $ EXAMPLES_HOME (рядом с файлом pom.xml ). Давайте кратко рассмотрим основные части этого файла.

Элемент <api-classes> просто сообщает Enunciate, какие классы должны использоваться для определения API веб-службы. По умолчанию Enunciate предполагает, что все классы в проекте являются частью API веб-службы, но в приложении примеров есть много других классов, которые используются для управления пользовательским интерфейсом и никогда не предназначались для определения API веб-службы, поэтому мы имеем сообщить Enunciate, что только три класса в пакете org.apache.wicket.spring.common используются для определения нашего API веб-службы:

...
<api-classes>
  <include pattern="org.apache.wicket.spring.common.Contact"/>
  <include pattern="org.apache.wicket.spring.common.ContactDao"/>
  <include pattern="org.apache.wicket.spring.common.ContactDaoImpl"/>
</api-classes>
...

Баланс файла конфигурации используется для определения поведения в конкретном модуле Enunciate. Enunciate генерирует документацию нашего API веб-сервиса из JavaDocs наших классов API. Настраивая модуль docs , мы говорим Enunciate поместить документацию в каталог / api приложения и назначить заголовок документации.

Enunciate собирает API веб-службы в форме приложения Spring, и его необходимо объединить с приложением примеров. Мы делаем это путем слияния сгенерированного Enunciate файла web.xml с файлом примеров web.xml и путем «импорта» определений bean-компонентов приложения Contacts с определениями bean-компонентов приложения Enunciate. Для того, чтобы сделать это надежно, нам нужно переместить файл web.xml в $ EXAMPLES_HOME (рядом с файлом pom.xml), чтобы файл, который генерирует Enunciate, не запирался.

...
<modules>
  <docs docsDir="api" title="Petclinic API"/>
  <spring-app>
    <war mergeWebXML="web.xml"/>
    <springImport uri="classpath:applicationContext.xml"/>
  </spring-app>
</modules>
...


mv src / main / webapp / WEB-INF / web.xml.

 

Шаг 3. Аннотируйте классы API

SOAP Метаданные

Интерфейс службы нашего API веб-службы определяется интерфейсом org.apache.wicket.spring.common.ContactDao и связанной с ним реализацией org.apache.wicket.spring.common.ContactDaoImpl . Чтобы представить интерфейс SOAP, нам просто нужно применить некоторые метаданные JAX-WS к этим классам. В частности, мы применяем аннотацию @ javax.jws.WebService к интерфейсу ContactDao и ту же аннотацию к классу ContactDaoImpl , определяя интерфейс, который он реализует в соответствии со спецификацией JAX-WS.

Интерфейс Clinic определяет метод find () , который возвращает Iterator , который не является допустимым типом возврата для JAX-WS. Сейчас мы просто исключим его с помощью аннотации @ javax.jws.WebMethod, а затем изменим его рефакторинг на коллекцию или что-то в этом роде.

ContactDao.java

@WebService
public interface ContactDao {
  /**
   * @return total number of contacts available
   */
  int count();

  /**
   * @param qp sorting and paging info
   * @return iterator over contacts
   */
  @WebMethod (
    exclude = true
  )
  Iterator find(QueryParam qp);

  /**
   * @param id contact id
   * @return contact with matching id
   */
  Contact get(long id);
}

ContactDaoImpl.java

@WebService (
  endpointInterface = "org.apache.wicket.spring.common.ContactDao"
)
public class ContactDaoImpl implements ContactDao
{
 ...
}

ОТДЫХ Метаданные

Конечно, мы также хотим применить интерфейс REST к нашему API. Это можно сделать, применив аннотации JAX-RS к нашим классам обслуживания, но это немного сложнее из-за дополнительных ограничений API REST.

Прежде всего необходимо сопоставить службу с путем URI, применив аннотацию @ javax.ws.rs.Path к классу реализации ContactDaoImpl . Мы смонтируем клинику на пути «/ контакты».

Далее, поскольку вы ограничены ограниченным набором операций, вы должны аннотировать конкретные методы, которые должны быть включены в REST API. Вы должны указать метод HTTP, который используется для вызова метода, и подпуть, который используется для его обнаружения. Мы сделаем это простым, выставив только метод get () с помощью операции GET с помощью аннотации javax.ws.rs.GET и смонтировав метод по пути «/ contacts / contact / {id}» с помощью javax.ws .rs.Path аннотация. «{Id}» в пути будет указывать идентификатор контакта, который мы хотим получить . Это означает, что параметр метода должен быть аннотирован @ javax.ws.rs.PathParam аннотация, которая также используется для указания имени параметра пути.

Конечно, вы можете использовать другие методы, используя другие аннотации, но мы отошлем вас к документации JAX-RS, чтобы узнать, как это сделать. Также обратите внимание, что аннотации JAX-RS уровня метода могут применяться либо к интерфейсу, либо к классу реализации, но в этом случае мы применим их к интерфейсу.

ContactDao.java

@WebService
public interface Clinic {

  ...

  /**
   * @param id
   *            contact id
   * @return contact with matching id
   */
  @GET
  @Path ("contact/{id}")
  Contact get(@PathParam("id") long id);

}

ContactDaoImpl.java

@Path ( "/contacts" )
@WebService (
  endpointInterface = "org.apache.wicket.spring.common.ContactDao"
)
public class ContactDaoImpl implements ContactDao
{
 ...
}
Эти классы можно скачать здесь и здесь .

Еще одна вещь необходима для предоставления REST API. Поскольку по умолчанию конечные точки REST будут предоставлять данные XML, мы должны предоставить корневые элементы XML для ответов XML. Для этого мы просто аннотируем класс org.apache.wicket.spring.common.Contact с помощью @ javax.xml.bind.annotation.XmlRootElement .

Contact.java

@XmlRootElement
public class Contact {
  ...
}

 

Шаг 4: Построить и развернуть

Вернемся к командной строке:


мвн чистая пристань: взорвалась

 

Вот слава

Ваше приложение полностью функционально по адресу http: // localhost: 8080 / wicket-examples / .

Ознакомьтесь с документацией по вашему новому API веб-службы по адресу http: // localhost: 8080 / wicket-examples / api / :

Все задокументировано, снято с комментариев JavaDoc. Вот документация для SOAP API:

И документация для REST API:

И вы можете скачать клиентские библиотеки, которые генерируются Enunciate и могут использоваться для вызова вашего API веб-сервиса:

А как насчет вашего WSDL? HTTP: // локальный: 8080 / калитка-примеры / API / ns1.wsdl

А как насчет вашей XML-схемы? HTTP: // локальный: 8080 / калитка-примеры / API / ns0.xsd

Хотите увидеть свой API в действии? Ваши конечные точки SOAP монтируются в подконтексте / soap , а ваши конечные точки REST монтируются в подконтексте / rest . Чтобы просмотреть контакт, просто используйте путь, который мы определили с помощью аннотаций JAX-RS относительно подконтекста / rest . Поэтому для просмотра контакта, идентифицируемого идентификатором «1», мы используем http: // localhost: 8080 / wicket-examples / rest / contacts / contact / 1 :

Для удобства тот же ресурс XML также можно найти по адресу http: // localhost: 8080 / wicket-examples / xml / contacts / contact / 1 . И если вы хотите получить тот же ресурс, что и JSON, вы можете использовать http: // localhost: 8080 / wicket-examples / json / contacts / contact / 1 .

И дальше …

Ну, вот как легко добавить API веб-сервиса в ваше приложение Wicket. Но мы только слегка поцарапали поверхность того, что может сделать Enunciate. Как насчет всего этого:

  • Безопасность (HTTP Auth, OAuth, вход в систему на основе форм, управление сеансами и т. Д.)
  • Конечные точки GWT RPC и клиентский JavaScript для доступа к ним.
  • Конечные точки AMF и ActionScript на стороне клиента для доступа к ним.
  • Потоковый API для больших запросов.
  • И т.п.

На данный момент, это только вопрос конфигурации ….

Если вы пропустили другие части серии, вы все равно можете поймать их здесь, в Javalobby:

36
Share: