jira ao UpgradeTask

插件发布到市场后，后续版本迭代的过程中，可能会对ao实体类的字段作添加或删除，或者要将某一字段的值映射解析到另一字段上。

本来这个工作，可以在插件启动的时候，在实现了com.atlassian.sal.api.lifecycle.LifecycleAware 接口的类onStart方法类完成。

但是历史版本更新了哪些字段不好维护，以前查看其它插件的代码时有看到版本更新任务的代码，但是因为实际工作中用的很少，就没去细看。

这几天查看atlassian的文档时，发现有一篇专门介绍如何处理upgradTask的文档。其实这篇文档是在一个系列中的，话说回来，atlassian插件开发的文档虽然挺全的，但是总体的文档结构还是有点乱的。

官网链接：处理AO升级任务

下文是对文档上的一些内容的截取

---

比如说我们之前有一个Todo类，它继承了Entity

@Preload 
public  interface  Todo  extend Entity { 
    void  setUserName （String  userName ）;

    String  getUserName （）;

    String  getDescription （）;

    void  setDescription （String  description ）;

    boolean  isComplete （）;

    void  setComplete （boolean  complete ）; 
}

Todo类中维护了一个userName字段，但是在后续的开发中，用户需要维护的信息很多，不止是用户名这么简单了。此时我们需要重新建一个User表，用来存放用户信息。

public interface User extends Entity
{
    String getName();
    void setName(String name);
}

Todo类也得做修改

package com.atlassian.tutorial.ao.todo;

import net.java.ao.Entity;
import net.java.ao.Preload;
import net.java.ao.schema.NotNull;

@Preload
public interface Todo extends Entity
{
    @NotNull
    void setUser(User user);

    @NotNull
    User getUser();

    String getDescription();

    void setDescription(String description);

    boolean isComplete();

    void setComplete(boolean complete);
}

之前service里的方法当然得修改，但这不是我们这里讨论的重点，接下来我们看，如何使用upgradetask更新数据库数据。

首先在ao包下面新建一个pacakge，名为upgrade.v2(官网上还建了v1包，但是那个升级改动较小，这里就不详述了)。

每次版本更新都要新建一个（v版本号）的包，包内存放需要更新的数据库实体类(从ao.entity包内复制过来，并做相应的改动。它不会在数据库内重新建一张表，只是用来记录更新信息)和更新任务类

package com.atlassian.tutorial.ao.todo.upgrade.v2;

import net.java.ao.Entity;
import net.java.ao.Preload;
// 保留了需要更新掉的字段user_name和需要新增的user_id字段（即getUser）
@Preload
public interface Todo extends Entity
{
    void setUserName(String userName);

    String getUserName();

    void setUser(User user);

    User getUser();

    String getDescription();

    void setDescription(String description);

    boolean isComplete();

    void setComplete(boolean complete);
}

user表是新增的，没有改动，直接复制过来

接下来就是更新的代码类了

package com.atlassian.tutorial.ao.todo.upgrade.v2; // (1) 引用upgrade.v2包下的类

import com.atlassian.activeobjects.external.ActiveObjects;
import com.atlassian.activeobjects.external.ActiveObjectsUpgradeTask;
import com.atlassian.activeobjects.external.ModelVersion;
import com.google.common.collect.ImmutableMap;
import net.java.ao.Query;

public final class TodoUpgradeTask002 implements ActiveObjectsUpgradeTask
{
    @Override
    public ModelVersion getModelVersion()
    {
        return ModelVersion.valueOf("2"); // (2) 版本设置为2
    }

    @Override
    public void upgrade(ModelVersion currentVersion, ActiveObjects ao)
    {
        ao.migrate(Todo.class, User.class); // (3) 声明需要操作的类

        Todo[] todos = ao.find(Todo.class); // (4) 实际升级，设置User对应的userName。
        for (Todo todo : todos)
        {
            todo.setUser(getOrCreateUser(ao, todo.getUserName()));
            todo.save();
        }
    }

    private User getOrCreateUser(ActiveObjects ao, String userName)
    {
        User[] users = ao.find(User.class, Query.select().where("NAME = ?", userName));
        if (users.length == 0) {
            return createUser(ao, userName);
        } else if (users.length == 1) {
            return users[0];
        } else {
            throw new IllegalStateException("There shouldn't be 2 users with the same username! " + userName);
        }
    }

    private User createUser(ActiveObjects ao, String userName)
    {
        return ao.create(User.class, ImmutableMap.<String, Object>of("NAME", userName));
    }
}

最后，需要在atlassian-plugin.xml中配置

 <ao key="ao-module">
        <description>The module configuring the Active Objects service used by this plugin</description>
        <entity>com.atlassian.tutorial.ao.todo.Todo</entity>
        <entity>com.atlassian.tutorial.ao.todo.User</entity>
        <upgradeTask>com.atlassian.tutorial.ao.todo.upgrade.v1.TodoUpgradeTask001</upgradeTask>
        <upgradeTask>com.atlassian.tutorial.ao.todo.upgrade.v2.TodoUpgradeTask002</upgradeTask>
    </ao>

执行，下面是官网给出的执行日志，

[INFO] [talledLocalContainer]  INFO - assian.activeobjects.internal.ActiveObjectUpgradeManagerImpl - Starting upgrade of data model, current version is 1
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - CREATE TABLE AO_3F7D93_USER (
[INFO] [talledLocalContainer]     ID INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 1) NOT NULL,
[INFO] [talledLocalContainer]     NAME VARCHAR(255),
[INFO] [talledLocalContainer]     PRIMARY KEY(ID)
[INFO] [talledLocalContainer] )
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - ALTER TABLE AO_3F7D93_TODO ADD COLUMN USER_ID INTEGER
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - ALTER TABLE AO_3F7D93_TODO ADD CONSTRAINT fk_ao_3f7d93_todo_user_id FOREIGN KEY (USER_ID) REFERENCES AO_3F7D93_USER(ID)
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - CREATE INDEX index_ao_3f7d93_todo_user_id ON AO_3F7D93_TODO(USER_ID)
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - SELECT * FROM AO_3F7D93_TODO
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - SELECT ID FROM AO_3F7D93_USER WHERE NAME = ?
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - INSERT INTO AO_3F7D93_USER (NAME) VALUES (?)
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - UPDATE AO_3F7D93_TODO SET USER_ID = ? WHERE ID = ?
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - SELECT ID FROM AO_3F7D93_USER WHERE NAME = ?
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - UPDATE AO_3F7D93_TODO SET USER_ID = ? WHERE ID = ?
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - SELECT ID FROM AO_3F7D93_USER WHERE NAME = ?
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - INSERT INTO AO_3F7D93_USER (NAME) VALUES (?)
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - UPDATE AO_3F7D93_TODO SET USER_ID = ? WHERE ID = ?
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - SELECT ID FROM AO_3F7D93_USER WHERE NAME = ?
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - UPDATE AO_3F7D93_TODO SET USER_ID = ? WHERE ID = ?
[INFO] [talledLocalContainer]  INFO - assian.activeobjects.internal.ActiveObjectUpgradeManagerImpl - Finished upgrading, model is up to date at version 2
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - ALTER TABLE AO_3F7D93_TODO DROP COLUMN USER_NAME
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - ALTER TABLE AO_3F7D93_TODO DROP CONSTRAINT fk_ao_3f7d93_todo_user_id
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - ALTER TABLE AO_3F7D93_TODO ALTER COLUMN USER_ID INTEGER NOT NULL
[INFO] [talledLocalContainer] DEBUG -                                              net.java.ao.sql - ALTER TABLE AO_3F7D93_TODO ADD CONSTRAINT fk_ao_3f7d93_todo_user_id FOREIGN KEY (USER_ID) REFERENCES AO_3F7D93_USER(ID)

最后几行可以看出，在完成升级任务之后，数据库的表结构也变了，user_name字段被移除