jira插件开发技术文档
1 搭建插件开发环境
以下是搭建插件开发环境的步骤.
目前开发的PALMS的Plugin插件主要是想在Palms System下的Browser Project中显示。
准备：JDK1.5，Atlassian Plugin SDK 3.0.1，JIRA 4.0.1（无所谓）。最好机子能连上网，我在公司可是悲剧的了，总是拷来拷去的。
Setting up your Plugin Development Environment：
1.1 install your java（配置java环境略去）。
1.2 Install the Atlassian Plugin SDK 3.0.1
Download：
https://https://www.360docs.net/doc/5f13322717.html,/content/repositories/atlassian-public/com/atlassian /amps/atlassian-plugin-sdk/选择符合你要求的版本，一个看你使用JIRA版本、JDK版本。
download 完了，unzip Atlassian Plugin SDK3.0.1zip 到你想的目录下。如
（D:\Atlassian\atlassian-plugin-sdk-3.0.1，接下来我们把路径
D:\Atlassian\atlassian-plugin-sdk-3.0.1\bin与
D:\Atlassian\atlassian-plugin-sdk-3.0.1\apache-maven\bin添加到我的环境变量Path 下。右键“我的电脑”-“属性”-“高级”-“环境变量”-选择“系统变量”或当前用户“用户变量”，选择“Path”-“编辑”，将其上粘贴上即可。如下图
好啦，现在Atlassian Plugin SDK3.0.1安装好了。看看能不能用吧。
Open a command window（window+R：输入cmd），键入c:\>mvn -v可查看JDK版本及其他信息，再键入c:\>mvn，回车后看到一大堆信息，显而易见的有个Build Error信息。没关系，出现这个就是说该安装环境很Ok的啦。如图：
Plugin SDK 已经安装ok，接下来安装Development IDE，本文档使用的是eclipse作为开发IDE工具，当然还有其他的IDE也行，只要能支持maven2行，需要知道更多就到
https://www.360docs.net/doc/5f13322717.html,/display/DEVNET/Setting+up+your+Plugin+Developme
nt+Environme nt
看JIRA提供的Steps。
2 Configuring eclipse to user the SDK
要想Eclipse能使用的Atlassian Plugin SDK，首先的先创建一个Plugin Project。官网上的步骤是这样的。
好了，既然要创建一个Plugin Project，我们就给他创建一个吧，而且创建的Plugin Project 都是用maven命令来完成的。
Create a Plugin Skeleton（创建一个插件框架）
我们在任意的Disk中的某一个目录下创建这个Plugin Project，这个没有绝对的约束。
2.1 用命令进入一个插件开发工作空间目录cd /…/工作空间目录
比如在本地进入C:\BOCCC_WORKSPACE\PALMS，接下来马上使用maven中的命令真正开始Plugin Skeleton的创建吧。
2.2 接着上面的命令在目前所在工作空间中再输入：atlas-create-jira-plugin
按回车键，当看到该命令停止时，会让你输入四个参数,输入的第一个参数groupId是默认的package（官网上有提到），第二参数artifactId就是你创建Plugin的名称啦，第三个version一看就知道是版本号啦，最后一个就是你的package名称，执行过程中也许会从不同站点下载很多的资源，当然很多都是用不到的，这个就没办法控制啦。如果执行顺利，我们会在最后看到Build Successful字样。如下图则表示这一步命令已经OK啦。
注意：执行该命令期间，需要看看log信息，以便解决一些问题。如有些警告错误，没关系，这可以忽略，只要不是出现missing之类且让你安装该资源时，特别是一些jar。一旦出现让你安装丢失的一些jars时，你可要按照下面的命令去安装你自己从网上刚download下的jar，如果我们丢失的是jira-soapclient-4.0.1-1.jar资源，那么我们将执行下面的命令（注意看改名中附带的参数与我们jar关系），-Dfile参数后面使我们下载该jar存放在我们本地的路径。执行该命令后，我们再次启动输入命令atlas-create-jira-plugin，这样的话就可以解决该丢失问题。
安装额外的jar的命令：（如安装TIMCommon.jar）
mvn install:install-file
-DgroupId=com.atlassian.jira.plugins-DartifactId=TIMCommon -Dversion=1.0
-Dpackaging=jar -Dfile=C:\mnt\san\COMMON\lib\tim\TIMCommon.jar
当atlas-create-jira-plugin这一步成功后，我们回到本地去查看到底发生了什么变化。进入到Disk C:\BOCCC_WORKSPACE\PALMS下，你看到了什么？对，这里已经创建了一个以TestPluginProject的文件夹，那么该文件夹的结构如何呢？看下图
这就是执行atlas-create-jira-plugin命令后给我们带来的结果。注意该文件下的有一个pom.xml文件，等接下来的所有命令都会在此文件的根目录下去执行。好，我们接着下一步操作。
Start the Host Application with your Plugin Installed.
Open comman window 中进入到pom.xml文件所在的根目录
C:\BOCCC_WORKSPACE\PALMS\TestPluginProject下，输入命令：atlas-run 只要执行完成看到图中红框所示信息，则这一步也是成功的。看图
因为执行这些命令时，需要从网上下载很多文件，要花点时间。当看到最后这点红色框中信息时，这一步也说明ok了。
看log信息，我们打开浏览器输入：http://localhost:2990/jira，在登录页面输入admin与admin。
进入后来到点击administration，一直往下拉，在左边找到plugin，点击后会在右边出现我们刚才创建的plugin。也就是TestPluginProject 如图所示，点击TestPluginProject 看到如下信息
好，这一步我们也都ok啦，做下一步吧。
3 Generate Project Files for your IDE
到目前为止，这一系列的命令后，我们的插件算是已经很ok啦，那么我们如果这个时候将生成的这个TestPluginProject工程导入到我们的Eclipse IDE里面，能成功吗？当我们在编写coding中能引用到我们需要的资源吗？No，不行。那么我们接下来就要做SDK 与我们的Eclipse IDE的桥梁吧。
3.1 先创建一个插件的工作空间
下面命令是使得C:\BOCCC_WORKSPACE\PALMS这个目录变成一个eclipse的工作空间打开command window，进入到
C:\BOCCC_WORKSPACE\PALMS，输入我跟换后命令开始执行（官网提供该命令总报错）
输入此命令：
mvn eclipse:add-maven-repo -Declipse.workspace C:\BOCCC_WORKSPACE\PALMS
執行後？有一個 .metadata和.jazz3生成
官网提供命令：atlas-mvn eclipse:add-maven-repo -Declipse.workspace
C:\BOCCC_WORKSPACE\PALMS
在我使用SDK 3.2.4版本时，执行此命令后会报一个错:
The plugin 'org.apache.maven.plugins:maven-F-plugin' does not exist or valid version could be found。
后来改换成SDK 版本后该问题被解决。当这一步我们执行成功后，那么马上做下一步，
3.2 把TestPluginProject目录变成项目工程
进入到C:\BOCCC_WORKSPACE\PALMS\TestPluginProject
输入命令：atlas-mvn eclipse:eclipse
该命令执行完成后，我们回到我们的本地
C:\BOCCC_WORKSPACE\PALMS\TestPluginProject下的指定工程看看又有什么变化。
有一个.settings为名的文件被生成，到目前我还没怎么仔细去看它内部到底是怎么回事，不过貌似都是些classpath的设置吧（我这么想的）。
好，到这一步终于算是完成啦，由于第一次需要下载太多的资源，时间花的比较长，我在公司时电脑可开了一个晚上呢，等回去看的时候总共花了137分钟，看到让人害怕。
先歇歇，等会我们再启动我的Eclipse IDE，将我们生成的Plugin Project 导入到IDE 下，一定是将我们创建那个Plugin Skeleton步骤的Plugin Project啊，不要将它复制到你的IDE workspace后在导入到你的IDE下，这样的将会导致不同步。
天哪，把Plugn Project 导入到你的IDE中后，目录结构可如下图：
java代码，也就是你自己业务逻辑java代码实现需要在src/main/jave下去coding，而我们的国际化文件及view页面则要在scr/main/resources下放置。
而最主要的就是，我们要开发那一种插件模式呢？这个就得必须在
atlassian-plugin.xml文件中左文章了。这个都可以去他的官网查看资料，貌似网上也有不少的说明。
最后需要注意点的是，我们根目录下的一个pom.xml文件，里面有几个选项有点意思，我们可以先看看，截取部分代码,如图：
其中红色框中的值会作为该插件的一个url动作。而且，如果该文件被修改后，必须要再次进入到pom.xml所在目录下执行atlas-mvn eclipse：eclipse命令。这个是官网上强调的。
最后，当我们编写代码后，我们仍需要执行命令：atlas-cli，之后再输入pi即可。之后我们进入到目录下将TestPluginProject-1.0.jar复制到JIRA指定插件安装目录下（{jira_home}\Application Data\JIRA\plugins\installed-plugins下面），重启JIRA Server 后行了。如图是工程下打好的jar包和插件指定目录下放置的jar包：
之后所有工程开发后的改动只要在插件工程的pom.xml文件目录下执行atlas-cli与pi 命令就行了，再就是复制jar文件到JIRA安装目录下，重启服务就算完成啦。
4 插件依赖到外部jar时开发步骤
在没有依赖到除了PALMS的lib库中其他jar的情况下我们的做法是:
插件jar是编译好后直接给到palms用的,所以在最开始的开发过程中我们只要打好插件jar包,直接给了部署同事(terry),然后就terry可以直接部署PALMS到SIT或者UAT,这样就能直接用插件了
但是当我们如果依赖到除了PALMS的lib库中其他jar时,等我们编译好jar,然后把依赖jar如xxx.jar放入到palms的/atlassian-jira/WEB-INF/lib下(或者任何能想的到的运行palms时所调用的库),却发现总是发现不了这个xxx.jar对应的类.
因此,这里记录的步骤就是依赖palms外部jar包的方法.
安装步骤:
4.1 在本地我们先在开发插件环境中安装上依赖的xxx.jar,方法是在命令行
执行:
mvn install:install-file -DgroupId=com.atlassian.jira.plugins
-DartifactId=xxx -Dversion=1.0 -Dpackaging=jar
-Dfile=C:\mnt\san\COMMON\lib\tim\xxx.jar
4.2 如果上面命令执行成功,此时xxx.jar就放入到了此目录下:
C:\Documents and
Settings\javadev\.m2\repository\com\atlassian\jira\plugins\xxx\1.0\xxx.jar
4.3 在插件工程中加上依赖到的这个jar来编译.
4.4 然后关键一步: 此外部xxx.jar和我们本插件工程怎么相互关联,打开工程下的pom.xml
加多如下代码:
关键地方就是groupId, artifactId, version填写,其他默认就行.
4.5 然后代码编写完成后再执行atlas-cli命令和pi命令打插件jar包
此时观察打好的jar的结构:
我们以TIMCommon.jar作为一个外部jar来看插件jar的内部结构
它多了一个lib目录,这里面就是我们依赖到的外部jar, jira在执行pi命令时把我们的外部jar 都放入到了这里面.
5 插件开发中遇到的一些问题
在PALMS中有许多类型的插件,比如自定义一个字段值在浏览任务时会显示不同图片的插件,比如在[浏览项目]后进入的页面左侧那些菜单包含的插件.
目前研究出的开发的插件就是下图这种:
点击浏览项目, 左侧菜单显示的[项目管理],[项目信息],[项目里程碑],[项目人天情况],这些都是插件.
那么我们最关心的就是点击这个菜单节点调用的哪个类的方法, 这个类在什么地方配置, 触发的这个页面又是在什么地方配置…
5.1 插件初始进入页面开发配置
首先来看我们的前台页面在什么地方配置的,我们以项目里程碑为例,我们的插件工程是projectMileStone:
初始页面在如下图中的index.vm:
页面都是vm格式的, 关于vm页面语法等网上查,这里略去.
它的配置文件在紧接着index.vm下面这里的atlassian-plugin.xml,代码如下:
url="${https://www.360docs.net/doc/5f13322717.html,anization.url}"/> location="https://www.360docs.net/doc/5f13322717.html,eStone"/> Palms Project Mile Stone Plugin Webwork Action Description. location="https://www.360docs.net/doc/5f13322717.html,eStone"/> name="https://www.360docs.net/doc/5f13322717.html,eStoneAction" alias="updatePhase"> class="https://www.360docs.net/doc/5f13322717.html,estone.panel.ProjectMileStoneTabPane l"> A Project mileStone based display of the Project. 1)在节点project-tabpanel中配置就是页面位置和对应的类,其中key名字给一个和其他插件不会重复的唯一的名字. Class是点击菜单后触发的类. 2)这个key的值是一个键值,配置国际化的键值,就是菜单显示的那个名字: 项目里程碑,国际化文件是在 location="https://www.360docs.net/doc/5f13322717.html,eStone"/> 这里配置,国际化文件在上图显示的名字为 https://www.360docs.net/doc/5f13322717.html,estone.properties文件夹中,名字就 是.milestone.properties. 3) 4) 5.2 插件进入初始页面对应的类开发步骤: 我们再来看这个index,vm所对应的类 https://www.360docs.net/doc/5f13322717.html,estone.panel.ProjectMileStoneTabPanel 代码如下: 首先继承了一个GenericProjectTabPanel类,这是jira库中的的,它有2个重写方 法:init 和getHtml,init是调用这个类初始化做的方法, getHtml就是点击菜单后页面调用的入口函数. 方法中的部分代码如下: 把一些信息如projectId,user等放入map,然后这样就会把一些信息传到前台. 5.3 关于调用Action的配置 到目前为止,我们做到了创建一个插件工程→,打包-->重启palms服务→进入[项目里程碑] 插件页面. 那么下一步研究的就是我们操作完页面后提交的action请求是怎么搞的. 当我们再页面上填写一些数据后,点击保存按钮,势必后与后台发生交互,那么此时就会调用一个acition请求. 1)首先还要看atlassian-plugin.xml文件,在这个文件中配置了一个webwork1节点,内容如下: Palms Project Mile Stone Plugin Webwork Action Description.