Создание пакета

В этом упражнении будет использоваться мастер создания проекта для создания проекта пакета OSGi.

1. Выберите в меню "Файл" пункт "Новый проект", чтобы открыть мастер создания проекта.
2. В категории Maven выберите элемент "Пакет Maven OSGi". Нажмите кнопку "Далее".
   
3. Введите текст MavenHelloService в качестве имени проекта. Нажмите кнопку "Готово".
4. Откройте окно свойств проекта и убедитесь, что в поле Формат исходных/двоичных файлов указано значение 1.6 и в категории "Исходные файлы" в поле Кодировка указано значение UTF-8.

При создании проекта пакета с использованием архетипа Maven OSGi среда IDE автоматически добавляет зависимость org.osgi.core-1.4.0.jar. В файле pom.xml элемент packaging имеет значение bundle (пакет).

<modelVersion>4.0.0</modelVersion>
<groupId>com.mycompany</groupId>
<artifactId>MavenHelloService</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>bundle</packaging>
<name>MavenHelloService OSGi Bundle</name>

Также в файле POM указано, что при сборке пакета используется подключаемый модуль maven-bundle-plugin.

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>2.0.1</version>
                <extensions>true</extensions>
            </plugin>
        </plugins>
    </build>

Добавление активатора пакета

В этом упражнении используется мастер для создания класса Java Installer, реализующего интерфейс org.osgi.framework.BundleActivator. Активатор пакета используется для управления жизненным циклом пакета. Экземпляр класса активатора создается при запуске пакета в контейнере.

Класс активатора не является обязательным для пакета OSGi, но метод start() в классе активатора можно использовать, например, для инициализации служб или других нужных пакету ресурсов. В этом упражнении будут добавлены несколько строк кода в класс, который будет выводить сообщения в "Окно вывода". Это позволит определить, когда пакет запускается и останавливается.

1. Щелкните правой кнопкой мыши к окне "Проекты" и выберите в меню "Создать" пункт "Прочее".
2. Выберите в категории OSGi элемент "Активатор пакета". Нажмите кнопку "Далее".
3. Введите имя класса Installer и выберите пакет com.mycompany.mavenhelloservice. Нажмите кнопку "Готово".
   
4. Откройте в редакторе файл Installer.java и измените методы start() и stop(), добавив следующие строки.

   package com.mycompany.mavenhelloservice;
   
   import org.osgi.framework.BundleActivator;
   import org.osgi.framework.BundleContext;
   
   /**
    *
    * @author nb
    */
   public class Installer implements BundleActivator {
   
       public void start(BundleContext context) throws Exception {
           String userName = context.getProperty("user.name");
           System.out.println("Maven Hello Service: Started OSGi bundle");
           System.out.println("User Name: " + userName);
       }
   
       public void stop(BundleContext context) throws Exception {
           System.out.println("Maven Hello Service: Stopped OSGi bundle");
       }
   
   }

5. Сохраните изменения.

Класс активатора пакета импортирует org.osgi.framework.BundleActivator и org.osgi.framework.BundleContext. По умолчанию создаваемый класс содержит два метода: start() и stop(). Платформа OSGi вызывает методы start() и stop() для включения и отключения функциональных возможностей пакета. При запуске пакета, компонент службы пакета регистрируется в реестре служб OSGi. После регистрации пакета, остальные пакеты могут найти в реестре и использовать через контекст пакета активные службы.

Среда IDE добавила в POM проекта элемент <Bundle-Activator> в конфигурацию maven-bundle-plugin.

<plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <version>2.0.1</version>
    <extensions>true</extensions>
      <configuration>
            <instructions>
                  <Bundle-Activator>com.mycompany.mavenhelloservice.Installer</Bundle-Activator>
            </instructions>
      </configuration>
</plugin>

При сборке пакета подключаемый модуль создает заголовок манифеста в файле манифеста проекта в файле JAR и указывает класс активатора пакета. При развертывании пакета среда выполнения OSGi ищет в файле манифеста заголовок Bundle-Activator.

Сборка и проверка пакета

В этом упражнении будет проведена сборка пакета OSGi. После этого можно проверить, что пакет работает правильно, развернув пакет во встроенном контейнере Apache Felix OSGi. Apache Felix включен в среду IDE, но можно зарегистрировать другие контейнеры OSGi, например, Eclipse Equinox.

1. Щелкните проект правой кнопкой мыши и выберите команду "Построить".

   После выбора команды "Построить", среда IDE собирает и устанавливает снимок JAR в локальном репозитории.

2. Выберите команду "Выполнить", и в окне "Вывод" отобразится следующая информация.

   Welcome to Felix
   ================
   
   Maven Hello Service: Started OSGi bundle
   User Name: nb

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

Создание интерфейса API пакета

В этом упражнении будет создан пакет и интерфейс.

1. Откройте мастер создания проекта и выберите в категории Maven элемент "Пакет Maven OSGi". Нажмите кнопку "Далее".
2. В поле "Имя проекта" введите MavenHelloServiceAPI. Нажмите кнопку "Готово".
3. Правой кнопкой мыши щелкните узел "Исходные файлы" проекта MavenHelloServiceAPI и выберите в меню "Создать" пункт "Интерфейс Java". Нажмите кнопку "Далее".
4. Введите текст HelloService в качестве имени класса.
5. Выберите пакет com.mycompany.mavenhelloserviceapi. Нажмите кнопку "Готово".
6. Измените интерфейс, добавив следующий код, и сохраните изменения.

   public interface HelloService {
   
       public String sayHello(String name);
   
   }

Определение пакетов для экспорта

В этом упражнении в окне свойств проекта будут выбраны пакеты, которые нужно сделать доступными для других пакетов и проектов. По умолчанию, классы пакета невидимы из других пакетов. Если требуется сделать некоторые классы пакета доступными, их следует указать в файле MANIFEST.MF. В этом случае другие пакеты могут импортировать указанные пакеты.

1. Щелкните правой кнопкой узел проекта и выберите команду "Свойства".
2. Выберите категорию "Экспортируемые пакеты" и затем пакет com.mycompany.mavenhelloserviceapi. Нажмите кнопку "OК".
   

   При выборе экспортируемых пакетов в окне свойств среда IDE добавляет в файл POM записи об экспортируемых пакетах.

   <plugin>
       <groupId>org.apache.felix</groupId>
       <artifactId>maven-bundle-plugin</artifactId>
       <version>2.0.1</version>
       <extensions>true</extensions>
       <configuration>
           <instructions>
               <Export-Package>com.mycompany.mavenhelloserviceapi</Export-Package>
               <Private-Package>com.mycompany.mavenhelloserviceapi.*</Private-Package>
           </instructions>
       </configuration>
   </plugin>

3. Правой кнопкой мыши щелкните узел проекта и выберите команду "Построить".

Подключаемый модуль maven-bundle-plugin обрабатывает создание файла MANIFEST.MF при сборке проекта. Если открыть файл MANIFEST.MF в скомпилированном файле JAR, видно, что подключаемый модуль добавил заголовок манифеста, определяющий экспортируемые пакеты, указанные в файле POM.

Manifest-Version: 1.0
Export-Package: com.mycompany.mavenhelloserviceapi
Bundle-Version: 1.0.0.SNAPSHOT
Build-Jdk: 1.6.0_17
Built-By: nb
Tool: Bnd-0.0.357
Bnd-LastModified: 1274279178454
Bundle-Name: MavenHelloServiceApi OSGi Bundle
Bundle-ManifestVersion: 2
Created-By: Apache Maven Bundle Plugin
Import-Package: com.mycompany.mavenhelloserviceapi
Bundle-SymbolicName: com.mycompany.MavenHelloServiceApi

Контейнер OSGi считывает заголовок манифеста Export-Package для определения доступных извне классов пакета. Например, в этом примере предоставляются классы пакета com.mycompany.mavenhelloserviceapi.

Развертывание пакета OSGi на сервере GlassFish

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

В этом упражнении пакеты OSGi будут развернуты на сервере GlassFish с помощью командной строки, поскольку в среде IDE отсутствует пользовательский интерфейс для этого действия. Существует несколько способов развертывания пакетов. В этом примере показано использование команды asadmin deploy. В качестве альтернативы можно скопировать JAR в папку domains/domain1/autodeploy/bundles в папке установки сервера GlassFish.

Дополнительные примеры и сведения о развертывании пакетов OSGi на сервере GlassFish приведены в Arun Gupta's TOTD #118: Managing OSGi bundles in GlassFish v3 - asadmin, filesystem, telnet console, web browser, REST, osgish. Также можно создать собственную наблюдаемую папку с помощью агента Apache Felix File Install, как описано в записи блога Sahoo Using filesystem operations to manage OSGi bundles in GlassFish.

1. Запустите сервер GlassFish в окне "Службы". Либо запустите сервер из командной строки.
2. Откройте терминал командной строки.
3. В командной строке перейдите в папку target, содержащую файл MavenHelloServiceApi-1.0-SNAPSHOT.jar.
4. Введите следующие команды.

   <glassfish-install>/glassfish/bin/asadmin deploy --type osgi MavenHelloServiceApi-1.0-SNAPSHOT.jar
   

   Где <glassfish-install> — папка установки сервера GlassFish. В окне терминала появится приблизительно такой текст:

   Authentication failed with password from login store: /Users/nb/.asadminpass
   Enter admin password for user "admin">
   
   Application deployed successfully with name MavenHelloServiceApi-1.0-SNAPSHOT.
   Команда развертывания успешно выполнена.

   Примечание. Нажмите клавишу ВВОД при запросе пароля (пароль администратора по умолчанию пустой).

В окне вывода среды IDE появится приблизительно такой текст:

INFO: MavenHelloServiceApi-1.0-SNAPSHOT was successfully deployed in 372 milliseconds.

Чтобы просмотреть в терминале список развернутых приложений и пакетов, введите следующую команду:

<glassfish-install>/glassfish/bin/asadmin list-applications
Authentication failed with password from login store: /Users/nb/.asadminpass
Enter admin password for user "admin">
MavenHelloServiceApi-1.0-SNAPSHOT

Добавление поддержки аннотаций SCR

В этом упражнении будет добавлена зависимость от библиотеки org.apache.felix.scr.annotations для включения поддержки аннотаций компонентов и служб. Подключаемый модуль Maven SCR будет обрабатывать аннотации и создавать файлы конфигурации XML при сборке пакета.

1. Разверните проект MavenHelloService в окне "Проекты".
2. Щелкните узел "Библиотеки" правой кнопкой мыши и выберите команду "Добавить зависимость".
3. Введите в поле "Идентификатор группы" текст org.apache.felix, в поле "Идентификатор артефакта" текст org.apache.felix.scr.annotations и в поле "Версия" текст 1.3.0. Нажмите кнопку "OК".

   Как альтернатива, можно ввести в окне критерии поиска (например, "scr.annotations") и провести поиск в репозиториям Maven.

Среда IDE объявляет зависимость в файле POM и отображает ее в узле "Библиотеки" в окне "Проекты".

Создание реализации интерфейса службы

В этом упражнении в пакете будет создан простой класс реализации и добавлены аннотации для объявления службы.

1. Щелкните узел "Исходные файлы" правой кнопкой мыши и выберите в меню "Создать" пункт "Класс Java". Нажмите кнопку "Далее".
2. Введите текст HelloImpl в качестве имени класса.
3. В поле "Имя пакета" введите com.mycompany.mavenhelloservice.impl. Нажмите кнопку "Готово".
4. Реализуйте интерфейс HelloService и затем реализуйте абстрактные методы.
5. Измените метод sayHello так, чтобы он возвращал строку name.

   public class HelloImpl implements HelloService {
       public String sayHello(String name) {
           return "Hello " + name;
       }
   }

6. Добавьте аннотации @Service и @Component.

   package com.mycompany.mavenhelloservice.impl;
   
   import com.mycompany.mavenhelloservice.api.HelloService;
   import org.apache.felix.scr.annotations.Component;
   import org.apache.felix.scr.annotations.Service;
   
   /**
    *
    * @author nb
    */
   @Component(name="hello-service")
   @Service
   public class HelloImpl implements HelloService {
   
       public String sayHello(String name) {
           return "Hello " + name;
       }
   
   }

   Обратите внимание, что атрибут name аннотации @Component используется для указания имени службы.

7. Исправьте выражения импорта для библиотек org.apache.felix.scr.annotations.Component и org.apache.felix.scr.annotations.Service.

Добавление подключаемого модуля Felix Maven SCR к POM

В этом упражнении в файл POM будет добавлен подключаемый модуль сборки maven-scr-plugin и указания для создания этим модулем файла конфигурации XML.

1. Раскройте узел "Файлы проекта" и откройте в редакторе файл pom.xml.
2. Добавьте в файл POM подключаемый модуль сборки maven-scr-plugin.

   <build>
       <plugins>
           <plugin>
               <groupId>org.apache.felix</groupId>
               <artifactId>maven-scr-plugin</artifactId>
               <executions>
                      <execution>
                           <id>generate-scr-scrdescriptor</id>
                           <goals>
                               <goal>scr</goal>
                           </goals>
                      </execution>
               </executions>
           </plugin>

Детальные сведения о поведении подключаемого модуля приведены на странице Apache Felix Maven SCR Plugin.

Сборка и развертывание пакета

В этом упражнении будет собран пакет и изучено содержание файла JAR пакета.

1. Щелкните проект правой кнопкой мыши и выберите команду "Построить".

   После выбора команды "Построить" среда IDE создает файл JAR в папке проекта target и копирует его в локальный репозиторий. В окне "Вывод" появятся приблизительно следующие данные.

   Installing com/mycompany/MavenHelloService/1.0-SNAPSHOT/MavenHelloService-1.0-SNAPSHOT.jar
   Writing OBR metadata
   ------------------------------------------------------------------------
   BUILD SUCCESSFUL
   ------------------------------------------------------------------------
   Total time: 5 seconds
   Finished at: Fri May 07 16:34:41 CEST 2010
   Final Memory: 23M/79M
   ------------------------------------------------------------------------
   

   Раскройте файл JAR, созданный в папке target, и проверьте, что файл MANIFEST.MF содержится в папке META-INF и что файл serviceComponents.xml содержится в папке OSGI-INF. Заголовки манифеста в файле MANIFEST.MF выглядят следующим образом.

   Manifest-Version: 1.0
   Service-Component: OSGI-INF/serviceComponents.xml
   Export-Package: com.mycompany.mavenhelloservice;uses:="com.mycompany.m
    avenhelloserviceapi,org.osgi.framework"
   Built-By: nb
   Tool: Bnd-0.0.357
   Bundle-Name: MavenHelloService OSGi Bundle
   Created-By: Apache Maven Bundle Plugin
   Build-Jdk: 1.6.0_17
   Bundle-Version: 1.0.0.SNAPSHOT
   Bnd-LastModified: 1274279195883
   Bundle-ManifestVersion: 2
   Bundle-Activator: com.mycompany.mavenhelloservice.Installer
   Bundle-SymbolicName: com.mycompany.MavenHelloService
   Import-Package: com.mycompany.mavenhelloservice,com.mycompany.mavenhel
    loserviceapi,org.osgi.framework;version="1.5"
   
   

   Подключаемый модуль maven-bundle-plugin создал заголовок манифеста в файле MANIFEST.MF, объявляющий класс активатора пакета, как и было указано в файле POM. Также в файле указано местоположение serviceComponents.xml - файла дескриптора, в котором объявлены службы.

   Подключаемый модуль maven-scr-plugin обрабатывает создание файла дескриптора serviceComponents.xml. В файле serviceComponents.xml объявлено имя, класс реализации и интерфейс указанных служб.

   <components xmlns:scr="http://www.osgi.org/xmlns/scr/v1.0.0">
       <scr:component enabled="true" name="hello-service">
           <implementation class="com.mycompany.mavenhelloservice.HelloImpl"/>
           <service servicefactory="false">
               <provide interface="com.mycompany.mavenhelloserviceapi.HelloService"/>
           </service>
           <property name="service.pid" value="hello-service"/>
       </scr:component>
   </components>

2. В командной строке перейдите в папку target, содержащую файл MavenHelloServiceApi-1.0-SNAPSHOT.jar.
3. Разверните пакет, набрав в терминале команду.

   <glassfish-install>/glassfish/bin/asadmin deploy --type osgi MavenHelloService-1.0-SNAPSHOT.jar
               

Теперь в окне вывода среды IDE при развертывании пакета отобразится приблизительно следующий текст.

INFO: Maven Hello Service: Started OSGi bundle
INFO: User Name: nb
INFO: MavenHelloService-1.0-SNAPSHOT was successfully deployed in 372 milliseconds.
        

Сообщение "Maven Hello Service: Started OSGi bundle" означает, что при развертывании был создан экземпляр класса активатора пакета Installer.

Создание проекта веб-приложения

В этом упражнении будет создан проект веб-приложения и добавлены зависимости от пакета MavenHelloService.

1. В меню "Файл" выберите пункт "Создать проект" и в категории Maven выберите пункт "Веб-приложение Maven". Нажмите кнопку "Далее".
2. Введите текст MavenHelloWebClient в качестве имени проекта. Нажмите кнопку "Готово".
3. Откройте окно свойств проекта и в категории "Выполнение" выберите сервер GlassFish Server 3.
4. В качестве относительного URL-адреса введите /HelloClient. Нажмите кнопку "OК".
5. Щелкните правой кнопкой мыши узел проекта и выберите в меню "Создать" пункт "Сервлет".
6. Введите HelloClient в качестве имени класса и выберите в списке пакетcom.mycompany.mavenhellowebclient. Нажмите кнопку "Готово".
7. Щелкните узел "Библиотеки" правой кнопкой мыши и выберите команду "Добавить зависимость".
8. Для поиска в локальном репозитории введите в поле "Текст запроса" текст helloservice.
9. Выберите пакет MavenHelloServiceAPI Snapshot в группе com.mycompany. Нажмите кнопку "OК".

   В качестве альтернативы, если проект пакета открыт в среде IDE можно перейти на вкладку "Открыть проекты" в диалоговом окне "Добавление зависимости" и выбрать проект из списка.

10. Откройте файл POM и добавьте элемент <scope> к описанию зависимости от MavenHelloServiceAPI и укажите, что зависимость имеет контекст provided.

    <dependency>
          <groupId>${project.groupId}</groupId>
          <artifactId>MavenHelloServiceAPI</artifactId>
          <version>${project.version}</version>
          <scope>provided</scope>
    </dependency>

Поскольку указан контекст provided пакет MavenHelloServiceAPI не включается в создаваемый архив WAR. Нет необходимости включать пакет, поскольку он был развернут на сервере в предыдущем разделе учебного курса.

Внедрение служб

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

1. Внедрите ресурсы службы с помощью аннотаций.

   @WebServlet(name="HelloClient", urlPatterns={"/HelloClient"})
   public class HelloClient extends HttpServlet {
   
      @Resource(mappedName="hello-service")
      HelloService helloService;

2. Измените метод processRequest, добавив оператор println для вызова метода службы sayHello

   out.println("<h1>Servlet HelloClient at " + request.getContextPath () + "</h1>");
   
   out.println(helloService.sayHello("Duke"));
   
   out.println("</body>");
   out.println("</html>");

3. Исправьте параметры импорта и сохраните измененные данные.

Сборка и запуск приложения

Теперь веб-приложение можно собрать и запустить.

1. Щелкните проект правой кнопкой мыши и выберите "Выполнить".

При выборе команды "Выполнить", среда IDE собирает приложение, развертывает на сервере архив WAR и открывает в обозревателе страницу HelloClient.

В окне "Файлы" видно, что в папке target содержится архив MavenHelloWebClient.war. Раскрыв архив WAR, можно увидеть, что он не содержит файл MavenHelloServiceAPI JAR.

Использование команды undeploy

При выполнении команды deploy параметр type использовался для указания OSGi. При выполнении этой команды пакет OSGi копировался в папку <GLASSFISH-INSTALL>/glassfish/domains/domain1/applications сервера GlassFish. Для отмены развертывания пакета, например MavenHelloService-1.0-SNAPSHOT.jar, можно ввести следующие команды.

<glassfish-install>/glassfish/bin/asadmin undeploy MavenHelloService-1.0-SNAPSHOT

Развертывание путем копирования пакетов OSGi

По умолчанию, пакеты OSGi, скопированные в папку autodeploy/bundles сервера GlassFish автоматически развертываются. Например, можно использовать команду копирования (например, cp) для копирования JAR пакета OSGi в папку <GLASSFISH-INSTALL>/glassfish/domains/domain1/autodeploy/bundles.

cp /Users/nb/Documents/nbproject/MyOSGiBundle/target/MyOSGiBundle-1.0-SNAPSHOT.jar modules/autostart

При копировании файла JAR в папку в окне вывода отображается приблизительно следующий текст.

INFO: Installed /Applications/NetBeans/glassfishv3/glassfish/modules/autostart/MyOSGiBundle-1.0-SNAPSHOT.jar
INFO: Started bundle: file:/Applications/NetBeans/glassfishv3/glassfish/modules/autostart/MyOSGiBundle-1.0-SNAPSHOT.jar

Можно проверить, что теперь этот файл JAR находится в папке autostart.

Можно использовать команду удаления (например, rm) для удаления файла JAR из папки autostart. При удалении файла JAR в окне вывода отображается приблизительно следующий текст.

INFO: Uninstalled /Applications/NetBeans/glassfishv3/glassfish/domains/domain1/autodeploy/bundles/MavenHelloService-1.0-SNAPSHOT.jar