Kitchen Duty Plugin

Kitchen Duty Planning REST Resource

Basically we will build the Kitchen Duty Planning REST Resource and the Kitchen Duty Planning REST Model which will persist our selected weeks and users to the database.

You also might want to look into the Story Workshop again to recapitulate what we are going to build now.

What do we need exactly?

After some serious brain usage on how to store the actual data of «who has Kitchen Duty in which week?» I came up with the Data-Model seen on the right.

The Week will be the actual week number in the year, and we don't care about the year in this tutorial. So if you had kitchen duty in week 24 this year you will have it the years after as well. With a little thinking ahead of how I want to use it in the JS Controller I basically will select a week via a date picker and calculate the week number in the frontend using moment.js

The User part is obvious. We will need to store a list of usernames in the database in relation with Weeks (@ManyToMany).

Concerning the REST Endpoint I will want to have an URL which I can fire GET requests on something like /planning/week/15/users and receive a list of users.

Obviously the other way round would be a PUT request on /planning/week/15/users with a list of users as request body to store the user list for the week 15.

And for our stretch-goal a GET request on /planning/user/bob/weeks should return a list of week numbers in which Bob has Kitchen Duty.

Week	n    m	User
week: Integer		username: String

How exactly do we persist our data?

Alright we know how we want to use our REST Endpoint from the perspective of the JS Controller. And we have some kind of clue on how the data should be stored theoretically.

There are two main possibilities to persist data in JIRA.

• Using the PluginSettingsFactory you have an easy way to persist data. But you don't have queries and cannot build relationships like you can with a real Database. So this is good if you just want to store simple stuff when you always know how to retrieve data from the PluginSettingsFactory (for example by a fixed key).
   
• Then there are Active Objects which let you use a real database with an ORM Interface. And that is definitely the choice we want to make here. So you might want to stroll around the Active Objects documents a little to get a grasp of it or just continue reading since I will also introduce you to it step by step.

Enabling Active Objects on our Project

All I will be writing about Active Objects is taken from the Developing your plugin with Active Objects Guide and the Getting Started with Active Objects Guide.

First of all add Active Objects dependency to your pom.xml.

<dependency>
   <groupId>com.atlassian.activeobjects</groupId>
   <artifactId>activeobjects-plugin</artifactId>
   <version>1.1.5</version>
   <scope>provided</scope>
</dependency>

We need a Component Import for ActiveObjects which will be the object we use to access the database.

package io.codeclou.kitchen.duty.rest;

import com.atlassian.activeobjects.external.ActiveObjects;
import com.atlassian.plugin.spring.scanner.annotation.imports.ComponentImport;
...

@Named ("myPluginComponent")
public class MyPluginComponentImpl implements MyPluginComponent {
   ...
   @ComponentImport
   private ActiveObjects activeObjects;
   ...
}

Now we create our first Entity Week and define the week as integer via getter/setter.

package io.codeclou.kitchen.duty.ao;

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

@Preload 
public interface Week extends Entity { 
    Integer getWeek();

    void setWeek(Integer week);
}

We just created the Week Entity now and we need to tell the Active Objects module of our Plugin where he can find our Entity. Therefore we add a section to our atlassian-plugin.xml file listing the Entities (Maybe there is some kind of nice Annotation to skip that step, but since the docs are very thin on that I don't know. So if you find out please tell me).

<ao key="ao-module">
    <description>The module configuring the Active Objects service used by this plugin</description>
    <entity>io.codeclou.kitchen.duty.ao.Week</entity>
</ao>

Creating a basic Week Entity and a persist-Endpoint

We are agile coders and wanna see basic results now of what we did. Therefore we will create a very basic persistTest-Endpoint to try out the ORM stuff provided by Active Objects. We will get rid of the endpoint later we just use it to get a feel of how Active Objects works.

package io.codeclou.kitchen.duty.rest;

import com.atlassian.activeobjects.external.ActiveObjects;
import com.atlassian.jira.bc.user.search.UserSearchService;
import com.atlassian.plugins.rest.common.security.AnonymousAllowed;
import com.atlassian.sal.api.transaction.TransactionCallback;
import io.codeclou.kitchen.duty.ao.Week;

import javax.inject.Inject;
import javax.inject.Named;
import javax.servlet.http.HttpServletRequest;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.util.ArrayList;
import java.util.List;

@Named
@Path("/planning")
public class KitchenDutyPlanningResource {

    private ActiveObjects activeObjects; 

    @Inject 
    public KitchenDutyPlanningResource(ActiveObjects activeObjects) {
        this.activeObjects = activeObjects;
    }

    public KitchenDutyPlanningResource() {
    }


    @GET
    @Path("/persistTest") 
    @Produces({MediaType.APPLICATION_JSON})
    @AnonymousAllowed
    public Response persistTest() {
        activeObjects.executeInTransaction(new TransactionCallback<Week>() 
        {
            @Override
            public Week doInTransaction() 
            {
                final Week testWeek = activeObjects.create(Week.class); 
                testWeek.setWeek(42);
                testWeek.save();
                return testWeek;
            }
        });
        return Response.ok("ok").build();
    }


    @GET
    @Path("/health")
    @Produces({MediaType.APPLICATION_JSON})
    @AnonymousAllowed
    public Response health() {
        return Response.ok("ok").build();
    }

}

Alright now startup JIRA with atlas-run but capture the output a file called jira-stdout.log so that we can grep it later. You need to have tee installed.

...
[INFO] [talledLocalContainer] INFORMATION: Server startup in 38377 ms
[INFO] [talledLocalContainer] Tomcat 8.x started on port [2990]
[INFO] jira started successfully in 58s at http://localhost:2990/jira
[INFO] Type Ctrl-D to shutdown gracefully
[INFO] Type Ctrl-C to exit

Open another terminal to execute some CURL commands and once JIRA has started up execute a GET Request to our persistTest Endpoint.

ok

Now our Week object with week 42 should have been persisted to the table Week in the database

Let's have a look into the Database

Alright now you need to know that JIRA runs a H2 Database when started with atlas-run. And it does NOT use HSQLDB anymore even though it has used HSQLDB up to some version of JIRA - but those days seem over.

You might have wondered why you needed to capture the STDOUT of JIRA previously to jira-stdout.log. Because on line 12131415 of one trillion overall lines that atlas-run echos you will find a line starting containing Database URL which tells you the location of the H2 Database. And since we want to have a look we need to know where the Database resides in order to connect.

Now stop the atlas-run by pressing CTRL+C (we can only look into the H2 DB if no other process uses it). And grep for the Database URL in the captured STDOUT.

[INFO] [talledLocalContainer]     Database URL   : jdbc:h2:file:/Users/...../target/jira/home/database/h2db

Copy the whole jdbc:h2:file:/Users/...../target/jira/home/database/h2db JDBC URL (I have shortened the path here)

In the same terminal we now start the H2 Database Console by executing the h2.jar file. (Depending on your SDK version it should be somehwere around that location and might have an alternate version number.)

Now a Browser Tab opens with the console and you just paste the JDBC URL and click connect.

You should see our Week table and if you execute a SELECT Statement on it you can see contents.

You can see the whole process of calling the testPersist Endpoint and connecting to the H2 Database in the following gif.

Adding User Class and Many-to-Many Relationship

Since we got Active Objects running successfully we now want to add a @ManyToMany relationship between User an Week.

And when you have read the docs you will note that we need a Mapping Entity for that case. We will call it UserToWeek.

But first we want to define the week and username as unique to avoid duplicate entries which are developer's nightmares.

package io.codeclou.kitchen.duty.ao;

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

@Preload
public interface Week extends Entity {

    @NotNull  
    @Unique  
    Integer getWeek();
    void setWeek(Integer week);

    @ManyToMany(value = UserToWeek.class)  
    User[] getUsers();
}

package io.codeclou.kitchen.duty.ao;

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

@Preload
public interface User extends Entity {

    @NotNull 
    @Unique 
    String getName();
    void setName(String week);

    @ManyToMany(value = UserToWeek.class) 
    Week[] getWeeks();
}

We just defined our real entities and the relation they have through UserToWeek so all that is left is to define the mapping entity.

package io.codeclou.kitchen.duty.ao;

import net.java.ao.Entity;

public interface UserToWeek extends Entity { 

    void setUser(User user); 
    User getUser();

    void setWeek(Week week); 
    Week getWeek();
}

That was all we needed to do to map the Many-To-Many relationship with Active Objects. And now don't forget to list the entities in the ao section of your atlassian-plugin.xml.

<ao key="ao-module">
    <description>The module configuring the Active Objects service used by this plugin</description>
    <entity>io.codeclou.kitchen.duty.ao.Week</entity>
    <entity>io.codeclou.kitchen.duty.ao.User</entity>
    <entity>io.codeclou.kitchen.duty.ao.UserToWeek</entity>
</ao>

We change the testPersist Endpoint to now persist a full relationship.

package io.codeclou.kitchen.duty.rest;
...

@Named
@Path("/planning")
public class KitchenDutyPlanningResource {
...

    @GET
    @Path("/persistTest")
    @Produces({MediaType.APPLICATION_JSON})
    @AnonymousAllowed
    public Response persistTest() {
        activeObjects.executeInTransaction(new TransactionCallback<Week>()
        {
            @Override
            public Week doInTransaction()
            {
                final Week testWeek = activeObjects.create(
                    Week.class, 
                    new DBParam("WEEK", 42)); 
                testWeek.save();

                final User user = activeObjects.create(
                    User.class, 
                    new DBParam("NAME", "ichiban")); 
                user.save();

                final UserToWeek relationship =
                           activeObjects.create(UserToWeek.class); 
                relationship.setUser(user); 
                relationship.setWeek(testWeek);
                relationship.save();

                return testWeek;
            }
        });
        return Response.ok("ok").build();
    }
...
}

We are all set now to start JIRA again and to test if we can really save our relationship. But before we do that do a quick atlas-clean before the next atlas-run so that the database gets purged. Otherwise you might run into Unique index or primary key violation errors since we have 4 week entries already all with week=42 values.

We startup JIRA again and call the persistTest Endpoint again.

ok

And by calling the testPersist endpoint a second time we will get a unique constraint exception as expected. That is fine since that only shows that the unique constraint works and we will be throwing away the persistTest Endpoint anyways.

We shutdown JIRA again and fire up the H2 Console again to see what tables have been created.

Creating the real Kitchen Duty Planning REST Resource with GET Endpoints for User and Week

Ok we have played around a little with active objects so far and now have our data model and entities in place. That means we can now create the real Endpoint Methods and throw away the testPersist Endpoint.

package io.codeclou.kitchen.duty.rest;
...

@Named
@Path("/planning")
public class KitchenDutyPlanningResource {
...

    /**
     * Get the Users assigned to the weekNumber.
     *
     * @param weekNumber
     * @return
     */
    @GET
    @Path("/week/{weekNumber}/users")
    @Produces({MediaType.APPLICATION_JSON})
    @AnonymousAllowed
    public Response getUsersForWeek(@PathParam("weekNumber") final Integer weekNumber) {
        Week[] weeks = activeObjects.executeInTransaction(new TransactionCallback<Week[]>() { 
            @Override
            public Week[] doInTransaction() {
                return activeObjects.find( 
                           Week.class,
                           Query.select().where("WEEK = ?", weekNumber)); 
            }
        });
        List<KitchenDutyPlanningResourceUserModel> users = new ArrayList<>(); 
        if (weeks != null && weeks.length > 0) { 
            for (User user : weeks[0].getUsers()) { 
                users.add(
                   new KitchenDutyPlanningResourceUserModel( 
                            user.getID(),
                            user.getName()
                   )
                );
            }
        }
        return Response.ok(users).build(); 
    }

    /**
     * Get the Weeks assigned to the User.
     *
     * @param weekNumber
     * @return
     */
    @GET
    @Path("/user/{username}/weeks")
    @Produces({MediaType.APPLICATION_JSON})
    @AnonymousAllowed
    public Response getWeeksForUser(@PathParam("username") final String username) { 
        User[] users = activeObjects.executeInTransaction(new TransactionCallback<User[]>() {
            @Override
            public User[] doInTransaction() {
                return activeObjects.find(User.class, Query.select().where("NAME = ?", username));
            }
        });
        List<KitchenDutyPlanningResourceWeekModel> weeks = new ArrayList<>();
        if (users != null && users.length > 0) {
            for (Week week : users[0].getWeeks()) {
                weeks.add(new KitchenDutyPlanningResourceWeekModel(week.getID(), week.getWeek()));
            }
        }
        return Response.ok(weeks).build();
    }
...
}

We have just used the REST-API-Pojos which we will define right now. No magic just getters and setters and some JAX-WS Annotations you have seen in previous steps of the tutorial already. The only fancy thing is the convenience constructor but yeah ... just copy paste those two since it's not a big deal.

package io.codeclou.kitchen.duty.rest;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "weeks")
@XmlAccessorType(XmlAccessType.FIELD)
public class KitchenDutyPlanningResourceWeekModel {

    @XmlElement
    private Integer id;

    @XmlElement
    private Integer week;

    KitchenDutyPlanningResourceWeekModel() { }

    KitchenDutyPlanningResourceWeekModel(Integer id, Integer week) {
        this.id = id;
        this.week = week;
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public Integer getWeek() {
        return week;
    }

    public void setWeek(Integer week) {
        this.week = week;
    }
}

package io.codeclou.kitchen.duty.rest;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "users")
@XmlAccessorType(XmlAccessType.FIELD)
public class KitchenDutyPlanningResourceUserModel {

    @XmlElement
    private Integer id;

    @XmlElement
    private String username;

    KitchenDutyPlanningResourceUserModel() { }

    KitchenDutyPlanningResourceUserModel(Integer id, String username) {
        this.id = id;
        this.username = username;
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }
}

Alright we again are at a point where we want to start JIRA and fire some request against our API to check it out.

Now we can query these two endpoints with the following example requests.

List assigned users for week 42.

[{"id":2,"username":"ichiban"}]

List weeks for user ichiban.

[{"id":2,"week":42}]

That is working fine. In the next section we will deal with assigning Users to Weeks and removing assignments.

Add the PUT and DELETE Endpoints to add a User to a Week or remove him

Now we add the functionality to add users to weeks and remove them from weeks. Therefore we will need a DELETE and PUT Endpoint which we add to the KitchenDutyPlanningResource Class.

We start with the PUT Endpoint to assign Users to Weeks.

...
    /**
     * Add the User to the Week
     *
     * @param weekNumber
     * @return
     */
    @PUT 
    @Path("/week/{weekNumber}/users")
    @Produces({MediaType.APPLICATION_JSON})
    @AnonymousAllowed
    public Response addUserToWeek(@PathParam("weekNumber") final Integer weekNumber, 
                                  final KitchenDutyPlanningResourceUserModel userParam) { 
        activeObjects.executeInTransaction(new TransactionCallback<Void>() { 
            @Override
            public Void doInTransaction() {
                //
                // WEEK
                //
                Week week = KitchenDutyActiveObjectHelper.findUniqueWeek( 
                                 activeObjects,
                                 weekNumber
                );
                if (week == null) {
                    week = activeObjects.create(
                                 Week.class,
                                 new DBParam("WEEK", weekNumber) 
                    );
                    week.save();
                }

                //
                // USER
                //
                User user = KitchenDutyActiveObjectHelper.findUniqueUser( 
                                 activeObjects,
                                 userParam.getUsername()
                );
                if (user == null) {
                    user = activeObjects.create(
                                 User.class,
                                 new DBParam("NAME", userParam.getUsername())
                    );
                    user.save();
                }

                //
                // Establish ManyToMany Relationship
                //
                UserToWeek relationship = KitchenDutyActiveObjectHelper
                                             .findRelationship(activeObjects, user, week); 
                if (relationship != null) {
                    // relation already exists
                    return null; 
                }
                relationship = activeObjects.create(UserToWeek.class); 
                relationship.setUser(user);
                relationship.setWeek(week);
                relationship.save();

                return null;
            }
        });
        return Response.ok().build(); 
    }
...

To break this up a little concerning readability now follows the DELETE Endpoint to remove Week assignments of Users in the same file.

...

    /**
     * Remove the User from Week
     *
     * @param weekNumber
     * @return
     */
    @DELETE 
    @Path("/week/{weekNumber}/users")
    @Produces({MediaType.APPLICATION_JSON})
    @AnonymousAllowed
    public Response deleteUserFomWeek(@PathParam("weekNumber") final Integer weekNumber,
                                  final KitchenDutyPlanningResourceUserModel userParam) { 
        activeObjects.executeInTransaction(new TransactionCallback<Void>() {
            @Override
            public Void doInTransaction() {
                //
                // WEEK
                //
                Week week = KitchenDutyActiveObjectHelper.findUniqueWeek( 
                                 activeObjects,
                                 weekNumber
                );
                if (week == null) {
                    // week does not exist => no relation to delete
                    return null;
                }

                //
                // USER
                //
                User user = KitchenDutyActiveObjectHelper.findUniqueUser( 
                                 activeObjects,
                                 userParam.getUsername()
                );
                if (user == null) {
                    // user does not exist => no relation to delete
                    return null;
                }

                //
                // Delete ManyToMany Relationship
                //
                UserToWeek relationship = KitchenDutyActiveObjectHelper
                                             .findRelationship(activeObjects, user, week); 
                if (relationship != null) {
                    activeObjects.delete(relationship); 
                }

                return null;
            }
        });
        return Response.ok().build();
    }
...

To prevent code duplication and improve readability of Endpoint-code I moved some common data-access-spaghetti-code into some static Methods of the KitchenDutyActiveObjectHelper Class. It should be pretty self-explanatory.

package io.codeclou.kitchen.duty.ao;

import com.atlassian.activeobjects.external.ActiveObjects;
import net.java.ao.Query;

public class KitchenDutyActiveObjectHelper {

    public static Week findUniqueWeek(ActiveObjects activeObjects, Integer weekNumber) {
        Week[] weekRes = activeObjects.find(Week.class, Query.select().where("WEEK = ?", weekNumber));
        if ((weekRes != null && weekRes.length > 0)) {
            return weekRes[0];
        }
        return null;
    }

    public static User findUniqueUser(ActiveObjects activeObjects, String username) {
        User[] userRes = activeObjects.find(User.class, Query.select().where("NAME = ?", username));
        if ((userRes != null && userRes.length > 0)) {
            return userRes[0];
        }
        return null;
    }

    public static UserToWeek findRelationship(ActiveObjects activeObjects, User user, Week week) {
        UserToWeek[] relationships = activeObjects.find(UserToWeek.class, Query.select().where("USER_ID = ? AND WEEK_ID = ?", user.getID(), week.getID()));
        if ((relationships  != null && relationships .length > 0)) {
            return relationships[0];
        }
        return null;
    }
}

Now we can fire up atlas-run once more and wait for JIRA startup.

Let's add a user called jimmy to a week 42. Fire up this curl command and it should return a HTTP 200 telling you it worked (we use the CURL -i parameter to echo out the response headers and return code). We have written our Endpoints in a way so that the CURLs are idemponent. So if you fire it a second time you will get a HTTP 200 as well but since jimmy already is assigned to week 42 nothing happens internally.

And by the way, we don't need to pass an ID for user since we don't know it and since the username has a unique constraint which makes it our technical primary key.

HTTP/1.1 200 OK
...
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Fri, 09 Sep 2016 16:52:06 GMT

Let's remove a user called ichiban from week 42.

HTTP/1.1 200 OK
...
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Fri, 09 Sep 2016 16:52:06 GMT

List assigned users for week 42.

[{"id":3,"username":"jimmy"}]

Now we have all our Endpoints in place and can continue to the next step. There we will actually use our Endpoints from the JS-Controller.

The graphic shows marked green which components we implemented in this section.