DocsICP FilingConsole
Documentation
Home Page Scalable Open Financial Architecture User Guide Middleware SOFABoot Advanced features Class isolation Introduction to Ark Plugin

Introduction to Ark Plugin

Updated at:
Copy as MD
Product
My Favorites

This topic describes the standard specifications and directory structure of Ark Plugins and how to use sofa-ark-plugin-maven-plugin plug-ins to package and publish Ark Plugins.

Plug-in specifications

The standard Ark Plugin must meet the following specifications:

  • You must specify a plug-in name for the plug-in. Default value: ${artifactId}. run time, a plug-in with the same name is not allowed, which can be considered a unique ID for the Ark Plugin.

  • The priority of the plug-in must be configured. The default value is 1000. A lower value indicates a higher priority.

  • A plug-in can be configured with at most one entry class activator, which is the entry of the container startup plug-in and is implemented in a unified manner. com.alipay.sofa.ark.spi.service.PluginActivator is the interface class. A plug-in with a high priority is started first.

  • Imported classes support two levels: package and class. Imported classes are loaded from other plug-ins first.

  • The export class supports two levels: package and class. The plug-in with the highest priority is exported first.

  • Resources in the classpath can be imported. Wildcards are not supported. Prioritize the search for specified resources from other plug-ins.

  • Resources in the classpath can be exported. Wildcards are not supported. Plug-ins with high priorities are preferentially exported.

Maven plug-ins

SOFAArk provides a Maven plug-in sofa-ark-plugin-maven-plugin by default, which can be used to package a project into an Ark plug-in in the standard format. The coordinates of the Maven plug-in are:

<plugin>
      <groupId>com.alipay.sofa</groupId>
      <artifactId>sofa-ark-plugin-maven-plugin</artifactId>
      <version>${demo.version}</version>
</plugin>

Goals configuration

sofa-ark-plugin-maven-plugin plug-ins provide goal: ark-plugin to package projects into standard Ark Plugins. The configuration is as follows:

<build>
    <plugin>
        <groupId>com.alipay.sofa</groupId>
        <artifactId>sofa-ark-plugin-maven-plugin</artifactId>
        <version>${sofa.ark.version}</version>
        <executions>
            <execution>
                <id>default-cli</id>
                <goals>
                    <goal>ark-plugin</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <! -- Configuration information -->
        </configuration>
    </plugin>
</build>

Complete configuration template

The complete sofa-ark-plugin-maven-plugin plug-in configuration template is as follows:

<plugins>
    <plugin>
        <groupId>com.alipay.sofa</groupId>
        <artifactId>sofa-ark-plugin-maven-plugin</artifactId>
        <version>${sofa.ark.version}</version>
        <executions>
            <execution>
                <id>default-cli</id>
                <goals>
                     <goal>ark-plugin</goal>
                </goals>
                
                <configuration>
                
                    <! -- Specify the directory where the packaged ${pluginName}.ark.plugin is stored; ${project.build.directory} by default -->
                    <outputDirectory>./</outputDirectory>
                    
                    <! -- Whether to install and publish the Ark Plugin to the repository. Default value: true. -->
                    <attach>true</attach>
                    
                    <! -- Ark Plugin can specify at most one com.alipay.sofa.ark.spi.service.PluginActivator interface implementation class -->
                    <activator>com.alipay.sofa.ark.service.impl.SampleActivator</activator>
                    
                    <! -- Configure the priority, the smaller the number, the higher the priority, the priority is to start, the priority is to export the class, the default 1000-->
                    <priority>2000</priority>
                    
                    <! -- Configure the name of the plug-in. Be sure to configure the pair, run time, is the unique ID of the plug-in. For example, sofa-rpc plug-ins can be configured as sofa-rpc. The default is ${artifactId}->
                    <pluginName>${ark.plugin.name}</pluginName>
                    
                    <! -- Set the classifier of the Ark Plugin. This parameter is empty by default. We recommend that you do not set this parameter if it is not necessary. -->
                    <classifier>ark-plugin</classifier>
                    
                    <! -- Configure imported classes and resources -->
                    <imported>
                        <! -- Configure the package to be loaded preferentially from other Ark plugins -->
                        <packages>
                            <package>javax.servlet</package>
                            <package>org.springframework.*</package>
                        </packages>
                        
                        <! -- Configure the classes to be loaded preferentially from other Ark plugins -->
                        <classes>
                             <class>com.alipay.sofa.rpc.config.ProviderConfig</class>
                        </classes>
                        
                        <! -- Configure resources to be loaded preferentially from other Ark plugins -->
                        <resources>
                             <resource>META-INF/spring/bean.xml</resource>>
                        </resources>
                    </imported>
                    
                    <! -- Configure export classes and resources -->
                    <exported>
                        <! -- Configure classes exported at the package level -->
                        <packages>
                            <package>com.alipay.sofa.ark.service</package>
                        </packages>
                        
                        <! -- Configure class-level export classes -->
                        <classes>
                            <class>com.alipay.sofa.ark.common.CommonUtils</class>
                            <class>com.alipay.sofa.mock</class>
                        </classes>
                        
                        <! -- Configure the resources to be exported by Ark Plugin -->
                        <resources>
                            <resource>META-INF/spring/bean.xml</resource>>
                        </resources>
                    </exported>
                    
                    <! -- Exclude the specified package dependency when packaging the plug-in. Format:${groupId:artifactId} or ${groupId:artifactId:classifier}-->
                    <excludes>
                        <exclude>org.apache.commons:commons-lang3</exclude>
                    </excludes>
                    
                    <! -- Exclude package dependencies that have the same groupId as the specified groupId when packaging the plug-in. -->
                    <excludeGroupIds>
                        <excludeGroupId>org.springframework</excludeGroupId>
                    </excludeGroupIds>
                    
                    <! -- Exclude package dependencies that have the same value as the specified artifactId when packaging the plug-in. -->
                    <excludeArtifactIds>
                        <excludeArtifactId>sofa-ark-spi</excludeArtifactId>
                    </excludeArtifactIds>
                    
                    <! -- Shade the specified JAR package to the Ark Plugin-->
                    <shades>
                        <shade>groupId:artifactId[:classifier]:version</shade>
                    </shades>
                </configuration>
            </execution>
        </executions>
    </plugin>
</plugins>

The configuration items meaning is as follows:

  • outputDirectory: Specifies the directory where the packaged ${pluginName}.ark.plugin is stored; ${project.build.directory} by default.

  • attach: specifies whether to install and publish the Ark plug-in to the repository. Default value: true.

  • activator: An Ark Plugin can specify at most one com.alipay.sofa.ark.spi.service.PluginActivator interface implementation class.

  • priority: Configure the priority. A smaller number indicates a higher priority. The default value is 1000.

  • pluginName: Configure the name of the plug-in, which must be correctly configured. run time, the name is the unique ID of the plug-in. For example, sofa-rpc plug-ins can be configured as sofa-rpc. The default value is ${artifactId}.

  • imported: Configure imported classes and resources.

    Important

    When you configure a package-level import class, if the package name contains an asterisk (*), all packages or classes that meet the package prefix are imported. If the package name does not contain an asterisk (*), all packages or classes that meet the package prefix are imported.

  • exported: Configure export classes and resources.

    Important

    If the package name contains an asterisk (*), all packages or classes that meet the package prefix are exported. If the package name does not contain an asterisk (*), all classes that meet the package prefix are exported.

  • excludes: Excludes the specified package dependencies when you package the plug-in. Format: ${groupId:artifactId} or ${groupId:artifactId:classifier}.

  • excludeGroupIds: When you package a plug-in, the package dependencies that have the same groupId as the specified groupId are excluded.

  • excludeArtifactIds: When you package a plug-in, the package dependencies that have the same value as the specified artifactId are excluded.

  • classifier: This parameter is empty by default, and only the Ark plug-in is packaged and generated. If this parameter is not empty, additional JAR packages are generated. We recommend that you do not set this parameter if it is not necessary.

  • shades: When you package a plug-in, the specified JAR package is shaded into the Ark Plugin.

Build an Ark Plugin

To generate a standard Ark plug-in for a common Java project, perform the following steps:

  1. In the project root directory, create an empty module to package the Ark Plugin and define the coordinates of the plug-in.

    Example:

    <dependency>
     <groupId>com.alipay.sofa</groupId>
     <artifactId>sofa-ark-plugin-demo</artifactId>
     <version>1.0.0</version>
</dependency>

  2. In the pom.xml file of this module, add the dependencies of other modules and third-party packages of the project, and configure sofa-ark-plugin-maven-plugin plug-ins.

  3. Run the mvn package command in the module directory or project root directory to generate the ark-plugin-demo.ark.plugin plug-in file in the configured outputDirectory directory. Run the mvn install command to install the plug-in file to the local Maven repository.

Publish the Ark Plugin

configure the repository address in the project master pom and run the mvn deploy command to publish the Ark Plugin.

If no classifier is set, the resulting Ark Plugin coordinates are:

<dependency>
      <groupId>com.alipay.sofa</groupId>
      <artifactId>sofa-ark-plugin-demo</artifactId>
      <version>1.0.0</version>
</dependency>

If the classifier=ark-plugin is set, the coordinates of the published Ark Plugin will contain the classifier = ark-plugin. The resulting Ark Plugin coordinates are:

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

Other applications can reference the plug-in by this coordinate.

Ark Plugin typical directory structure

The following figure shows the directory structure of the Ark Plugin that is generated by packaging the project: How to Package the Ark Plugin

.
├── META-INF
│ ├── MANIFEST.MF
│ └── maven
│ └ ── com.alipay.sofa
│ └ ── sample-ark-plugin
│ ├── pom.properties
│ └── pom.xml
├── com
│ └── alipay
│ └── sofa
│ └── ark
│ ├── plugin
│ │ └── mark
│ └── sample
│ ├── activator
│ ├── facade
│ └── impl
└── lib
     ├── sample-ark-plugin-0.6.0.jar
     ├── sample-ark-plugin-common-0.6.0.jar
     ├── sofa-ark-exception-0.6.0.jar
     └── sofa-ark-spi-0.6.0.jar

The files and directories related to the preceding directory structure are described as follows:

  • com/alipay/sofa/ark/plugin/mark: Marker file that indicates that the JAR package is an Ark Plugin file generated by sofa-ark-plugin-maven-plugin packaging.

  • META-INF/MANIFEST.MF: records the metadata of the plug-in. The following table describes the metadata of the plug-in. 

    Manifest-Version:1.0
groupId: com.alipay.sofa
artifactId: sample-ark-plugin
version:0.6.0
priority:100
pluginName: sample-ark-plugin
description:
activator: com.alipay.sofa.ark.sample.activator.SamplePluginActivator
import-packages:
import-classes:
import-resources:
export-packages: com.alipay.sofa.ark.sample.common
export-classes: com.alipay.sofa.ark.sample.facade.SamplePluginService
export-resources:Sample_Resource_Exported

  • lib/: The lib directory stores the common JAR packages that the plug-in project depends on. Generally, the JAR packages that the plug-in needs to be isolated from other plug-ins or businesses are included in these JAR packages.

  • com/alipay/sofa/ark/sample/*: The class files contained in the Ark Plugin module.

Previous：Ark package introductionNext：Introduction of Ark Biz