© 2006 intland software1 aron gombas architect, intland software extending & customizing...

© 2006 Intland Software 1

Aron GombasAron GombasArchitect, Intland SoftwareArchitect, Intland Software

Extending & customizing CodeBeamer


Customize, extend and integrate: why?

To adapt CB to your business!

CB conceptual extension points:• Remote API (also known as "web services API"):

– extend remotely, by accessing CB functionality from remote clients

• Listeners

– extend on the server side, by implementing event listeners

• Wiki plugins

– extend the wiki syntax (the wiki markup language), visualize your custom information


Typical use cases: when to use what?

Remote API:– importers & exporters (data exchange/backup, migration from legacy systems)– integration with external systems (e.g. Lotus Notes)– IDE plugins (e.g. our Eclipse plugin)

Listeners:– custom business rules: "tracker items can't be deleted unless their status is

CLOSED"– integration with external systems (e.g. sending JMS messages)

Wiki plugins:– integrate with external info providers (e.g. reports from an external system)– aggregate info from multiple sources to a single (portal-like) wiki page


Remote API: basics

• High-performance– based on the binary protocol: Hessian

• Language independent– clients in other languages than Java (C#, PHP, etc.)

• Secure– fine-grained security model (like at the web front-end)

• authentication: remote user must authenticate (with username + password)

• authorization: access rights control

• Extremely easy to use (see sample code later)– remote method calls look like local method calls


Remote API: supported ops

What can you do remotely?– authentication: login, logout, getServerInfo– users: create, update, delete ("CRUD"), findByName, findByProject ("finders")– projects: CRUD, finders + createFromTemplate– artifacts ("documents"): CRUD, finders + lock, unlock, upload, download– artifact comments: CRUD, finders– trackers: CRUD, finders + layout, options– tracker items: CRUD, finders + history, statistics– tracker items comments/attachments: CRUD, finders– associations: CRUD, finders– source code files: finders + commit history– forums: CRUD, finders– forum posts: CRUD, finders– reports: finders + execute– wiki pages: CRUD, finders + lock, unlock, upload, download, history– wiki page comments: CRUD, finders


Remote API: sample sequence


Remote API: sample code

// get all projects from the remote server

RemoteApi api = RemotingUtils.connect("https://localhost:8080/cb/remote-api");

String token = api.login("bond", "007");

ProjectDto projects[] = api.findAllProjects(token);

for(int i = 0; i < projects.length; i++) {

ProjectDto project = projects[i];

System.out.println(project.getName());

}

api.logout(token);

See more sample code in "cb-remote-api-4.1.1.zip"


Listeners

CB listener architecture:• listeners can receive notifications from events inside the CB server

• clear interface between the CB core and your custom code

– portability for future versions of CB

• follows the "Observer" design pattern conventions

– similar to AWT, SAX parsers, event driven system

• easy to use (see sample code later)


Listeners: supported events

• Types– Created-updated-deleted event for any entity type:

• "projectCreated", "trackerUpdated", "forumDeleted", etc.

– A couple of specials events like:

• "documentOpened", "sourceCodeModificationCommitted“, etc.

• Timing

– pre ("before the actual operation") events and post ("after") events

• Vetoable changes– any listener can cancel the operation its "pre" phase by throwing a

VetoException

– no vetoing in "post"


Listener: event sample

1. User clicks “OK” when creating a new tracker

2. All tracker listeners receive the “pre tracker created” event

3. If vetoed, the operation is rejected end

4. The tracker gets created

5. All tracker listeners receive the “post tracker created” event

6. End


Listeners: listener types

• ArtifactListener• AssociationListener• ForumListener• ForumPostListener• ProjectListener• SccListener• TrackerListener• TrackerItemListener• TrackerItemAttachmentListener• TrackerItemCommentListener• UserListener• WorkflowListener


Listeners: developing listeners

1. Write a concrete implementation class that implements one of the

previous Java interfaces

2. Register it to CB

• declaratively: by configuring it in "general.xml"

<listener id="myTrackerItemListener"

class="com.mycompany.event.impl.MyTrackerItemListener" />

That's it!


Listeners: sample code

public class LoggerListener implements ArtifactListener {

final static protected Logger log = Logger.getLogger(LoggerListener.class);

public void identifiableCreated(BaseEvent event) {

log.debug("identifiableCreated: " + getEventDescriptor(event));

}

public void identifiableUpdated(BaseEvent event) {

log.debug("identifiableUpdated: " + getEventDescriptor(event));

}

public void identifiableDeleted(BaseEvent event) {

log.debug("identifiableDeleted: " + getEventDescriptor(event));

}

// ... other event handlers here

protected String getEventDescriptor(BaseEvent event) {

return (event.isPreEvent() ? "PRE " : "POST ") + event.getUser()

+ " ["+ event.getRemoteAddress() +"] on "+ event.getSource();

}

}


CodeBeamer wiki plugins

• What is a "wiki plugin“?– when referenced from the wiki markup, it is invoked by the wiki engine and its

output inserted into the page– mechanism to extend the wiki syntax

[{TableOfContents title="My favourite things"}]

• CB wiki is built on the top of JSPWiki, but adding:– tight integration with other CB facilities– fine grained security– many more

• CB is using JSPWiki as its internal wiki rendering engine:– many times: a JSPWiki plugin can be used without any modification– sometimes: little tweaking is necessary– generally: writing a CB wiki plugin is 95% identical with writing a JSPWiki plugin

(a lot of sample code available!)


Wiki plugins: developing a Hello World sample

package cv.wiki.plugins;

import java.util.Map;

import com.ecyrd.jspwiki.WikiContext;import com.ecyrd.jspwiki.plugin.WikiPlugin;

public class HelloWorldDemoPlugin implements WikiPlugin {public String execute(WikiContext context, Map params) {

String name = (String)params.get("name");if(name == null) {

name = "World";}

return "Hello " + name + "!";}

}

Compile, add to CLASSPATH, try:

[{HelloWorldDemoPlugin}][{HelloWorldDemoPlugin name='Joe'}]

will print:

Hello World!Hello Joe!


Wiki plugins: more complicated samples

• Extend AbstractCodeBeamerWikiPlugin by your wiki class– rendering with Velocity: wiki output generated from templates (separate

presentation from logic, don't hardwire formatting to Java code)– accessing CB-specific info

• getUserFromContext() returns the currently signed in user• getPageFromContext() returns the currently rendered wiki page• access more info transitively:

– "getPageFromContext().getProject().getName()“

• Using the CB Service Layer (also known as Business Layer or Business Tier), e.g.:

– “find all tracker items assigned to the currently signed in user”– “find all forum posts in the current projects posted in the last 3 days”

• Read our 3 part tutorial at "CB Knowledge Base"


13. QA

© 2006 intland software1 aron gombas architect, intland software extending & customizing...

Documents

finders history

intland software4 remote

intland software7 remote

intland software5 remote

intland software6 remote

finders reports

finders lock

finders layout