Skip to content

Latest commit

 

History

History
116 lines (93 loc) · 4.83 KB

README_EN.md

File metadata and controls

116 lines (93 loc) · 4.83 KB
Raw

How to build an ark-plugin

Introduction

This sample project shows how to build an ark-plugin based on a normal java project with the tool of sofa-ark-plugin-maven-plugin

Background

Assuming such a situation, you develop a lib, however, some dependency conflict occurs when imported to the consumer project. To avoid this problem, you would hope to isolate your lib with the consumer project. Ark-Plugin employs the mechanism of classloader isolation. It runs on Ark-Container, any ark-plugin would be loaded by an independent classloader.

There are four concepts about ark-plugin:

  • Exported Class: classes contained in ark-plugin，loaded by ark-plugin-classloader, but can be resolved by other ark-plugin (if it imports) or consumer project.

  • Imported Class: if a ark-plugin configures this item, it prefers to resolve class from other ark-plugin which exports corresponding class.

  • Exported Resource: resources contained in ark-plugin，loaded by ark-plugin-classloader, but can be found by other ark-plugin (if it imports) or consumer project.

  • Imported Resource: if a ark-plugin configures this item, it prefers to find resource from other ark-plugin which exports corresponding resource.

Tools

The Maven plugin of sofa-ark-plugin-maven-plugin is provided to build a standard ark-plugin, and just needs some simple configurations. Details please refer to doc

Step by Step

Create a Maven Project

This sample project is a standard maven project, it contains two modules:

  • common module: contains some classes exported.
  • plugin module: contains plugin activator and plugin service.

One thing should be pointed out that dependencies imported by project also can be exported.

Configure sofa-ark-plugin-maven-plugin

The maven plugin of sofa-ark-plugin-maven-plugin is configured in the pom.xml of plugin module, it configures as follows:

<executions>
    <execution>
        <id>default-cli</id>
        
        <!-- goal executed to generate ark-plugin -->
        <goals>
            <goal>ark-plugin</goal>
        </goals>

        <configuration>

            <!--can only configure no more than one activator-->
            <activator>com.alipay.sofa.ark.sample.activator.SamplePluginActivator</activator>

            <!-- configure exported class -->
            <exported>
                <!-- configure package-level exported class-->
                <packages>
                    <package>com.alipay.sofa.ark.sample.common</package>
                </packages>

                <!-- configure class-level exported class -->
                <classes>
                    <class>com.alipay.sofa.ark.sample.facade.SamplePluginService</class>
                </classes>
                
                <!-- configure exported resource -->
                 <resources>
                    <resource>Sample_Resource_Exported</resource>
                </resources>
            </exported>
            </exported>

            <!--specify destination where ark-plugin will be saved, default saved to ${project.build.directory}-->
            <outputDirectory>../target</outputDirectory>

        </configuration>
    </execution>
</executions>

The configured items are explained as follows:

  • activator: startup entry of ark-plugin when running on ark-container; generally speaking, ark-plugin service would be published in the entry, similar to what SamplePluginActivator does.
  • exported pacakges: the package of com.alipay.sofa.ark.sample.common is exported, any class whose name start with com.alipay.sofa.ark.sample.common would be exported.
  • exported classes: the single class com.alipay.sofa.ark.sample.facade.SamplePluginService is exported.
  • exported resource: the resource Sample_Resource_Exported is exported.
  • outputDirectory: specify destination where ark-plugin would be saved when execute the maven command of mvn package

package/install/deploy

  • package: execute mvn package, the ark-plugin file generated would be saved to the configured value of outputDirectory.
  • install: execute mvn install, the ark-plugin would be installed local maven repository, its maven location would bring a classifier of ark-plugin.
  • deploy: execute mvn deploy, just as usual practice.

import

As what mentioned above, the maven location of ark-plugin would bring with a classifier of ark-plugin, so, to import the ark-plugin generated by this sample project, you should add the following dependency in your consumer project:

<dependency>
     <groupId>com.alipay.sofa</groupId>
     <artifactId>sample-ark-plugin</artifactId>
     <classifier>ark-plugin</classifier>
     <version>1.0.0-SNAPSHOT</version>
 </dependency>