Play Confluence 插件开发 - 插件测试模块配置文件介绍 (03)

     每个插件都必须有一个插件配置文件.名字为atlassian-plugin.xml.Confluence就是通过这个文件去识别到插件的. 通过SDK创建的插件项目会自动生成一份插件描述文件.对于大多数项目,需要我们手动修改文件,所以我们最好了解文件中的内容. 文件的位置位于项目主目录中的如下目录中(一个是插件本身的,一个是插件测试的):

<project_home>/src/main/resources,<project_home>/src/test/resources

一.插件测试模块配置文件

(1).我们今天先来介绍下插件测试模块的配置文件,如下是插件描述文件的根元素.

<atlassian-plugin key="${project.groupId}.${project.artifactId}-test" name="${project.name}" plugins-version="2"></atlassian-plugin>

属性	描述
key	用来标识插件模块.此属性是必须的,并且在插件中必须是唯一的,相当于插件的身份证号码.默认使用构建插件时填写的groupId和artifactId加字母组成.
name	插件的名称.用于在应用程序的菜单中显示.默认通过引用pom.xml文件的name来加载.(不应该在该值中使用单词“plugin”或“add-on”)

(2).接下来是plugin-info元素

包含插件信息,父元素是<atlassian-plugin>,支持多个嵌套元素.​​​​​​​

<plugin-info> <description>${project.description}</description> <version>${project.version}</version> <vendor name="${project.organization.name}" url="${project.organization.url}" /></plugin-info>

嵌套元素	描述
<description>	插件说明
<version>	插件版本
<vendor>	提供插件开发人员的信息
<param>	插件参数(示例中的两个参数分别提供了插件图标的位置和插件logo的位置)

(3).vendor元素

插件供应商.在插件管理中提供链接地址.父元素是<plugin-info>.

属性名称	描述
name	提供开发人员的姓名或公司的名称
url	提供一个网站地址

 

文件其余部分是组成插件的所有模块,里面有resource元素和web-resource元素.

(4).这个是国际化资源文件

<resource type="i18n" name="i18n" location="hello-world"/>

(5).接下来是component-import元素.组件导入模块,该模块允许访问其他插件共享的java组件.​​​​​​​

 <!-- from our base plugin --> <component-import key="myComponent" interface="com.jenseny.atlassian.tutorial.api.MyPluginComponent"/> <!-- from the product container --> <component-import key="applicationProperties" interface="com.atlassian.sal.api.ApplicationProperties" />

属性	描述
interface	要导入的java接口
key	插件模块的唯一标识符

第一个导入模块是我们创建的插件本身,要说第二个的话就要先介绍下共享访问层(Shared Access Layer).

二.共享访问层(Shared Access Layer).

(1).关于SAL. 它为常见的插件任务提供了一致的API,而与插件部署到的Atlassian应用程序(JIRA、Confluence、FishEye)无关,有点类似于java的一次编写,到处运行.SAL对于跨应用程序最有用.如果仅针对单个应用程序开发插件，则只需使用应用程序自己的API。如果你的插件将在两个或多个应用程序中运行,你会发现SAL的服务很有用.这些常见的服务包括但不限于:

1. 作业调度

2. 国际化查询

3. 插件的首选项设置

可以通过如下链接去查找需要的SAL服务.

https://developer.atlassian.com/server/framework/atlassian-sdk/sal-services/

怎么运行?下图从概念上描述了SAL,它是插件和应用程序(JIRA、Confluence、FishEye)之间的一层.假如插件在JIRA仪表板上提供一个Dashboard,并且需要存储用户首选项设置. 仪表板插件向SAL发送请求,要求将首选项保存在JIRA中.SAL通过SAL JIRA插件与JIRA通信.另外,仪表板插件可能需要将首选项保存在COnfluence中.仪表板插件将使用相同的SAL API调用,SAL会通过SAL Confluence插件与Confluence通信.

这是另一个图,提供了SAL在运行中的更多细节.

(2).使用SAL服务

要使用SAL服务,需要声明一个组件导入模块在插件描述文件中.例如,如果要获取UserManager,则组件导入应如下所示:

<component-import key="userManager" interface="com.atlassian.sal.api.user.UserManager" />

还需要在pom.xml中添加如下依赖(通过SDK创建的插件项目默认已添加该依赖)​​​​​​​

<dependency> <groupId>com.atlassian.sal</groupId> <artifactId>sal-api</artifactId> <version>2.0.0</version> <scope>provided</scope></dependency>

(3).SAL代码例子(分别用两种写法演示)

1.第一种

atlassian-plugin.xml​​​​​​​

<atlassian-plugin key="your-plugin-key" name="Your plugin name" plugins-version="2">    <component-import key="pluginSettingsFactory" interface="com.atlassian.sal.api.pluginsettings.PluginSettingsFactory" /></atlassian-plugin>

Example class​​​​​​​

public class Example {
 final PluginSettingsFactory pluginSettingsFactory;
 public Example(PluginSettingsFactory pluginSettingsFactory) { this.pluginSettingsFactory = pluginSettingsFactory; }
 public void storeSomeInfo(String key, String value) { // createGlobalSettings is nice and fast, so there's no need to cache it (it's memoised when necessary). pluginSettingsFactory.createGlobalSettings().put("my-plugin-namespace" + key, value); }
 public Object getSomeInfo(String key) { return pluginSettingsFactory.createGlobalSettings().get("my-plugin-namespace" + key); }
 public void storeSomeInfo(String projectKey, String key, String value) { // createSettingsForKey is nice and fast, so there's no need to cache it (it's memoised when necessary). pluginSettingsFactory.createSettingsForKey(projectKey).put("my-plugin-namespace" + key, value); }
 public Object getSomeInfo(String projectKey, String key) { return pluginSettingsFactory.createSettingsForKey(projectKey).get("my-plugin-namespace" + key); } }

2.第二种(直接在需要使用的地方添加注解即可)

 

Example class​​​​​​​

@Scannedpublic class Example {
 @ComponentImport private final PluginSettingsFactory pluginSettingsFactory;
 @Inject public Example(PluginSettingsFactory pluginSettingsFactory) { this.pluginSettingsFactory = pluginSettingsFactory; }
 public void storeSomeInfo(String key, String value) { // createGlobalSettings is nice and fast, so there's no need to cache it (it's memoised when necessary). pluginSettingsFactory.createGlobalSettings().put("my-plugin-namespace" + key, value); }
 public Object getSomeInfo(String key) { return pluginSettingsFactory.createGlobalSettings().get("my-plugin-namespace" + key); }
 public void storeSomeInfo(String projectKey, String key, String value) { // createSettingsForKey is nice and fast, so there's no need to cache it (it's memoised when necessary). pluginSettingsFactory.createSettingsForKey(projectKey).put("my-plugin-namespace" + key, value); }
 public Object getSomeInfo(String projectKey, String key) { return pluginSettingsFactory.createSettingsForKey(projectKey).get("my-plugin-namespace" + key); } }

     两种方法相对来说第二种更加简洁一些,我个人也比较喜欢第二种. 今天的话我们简单介绍了测试模块的配置文件,下节我们介绍下插件本身的配置文件,也是我们插件部署真正需要用到的.