PEtALS Developers' Guide
This document explains how to configure the developer's environment for PEtALS.
PEtALS Team Christophe HAMERLING
Christophe DENEUX
- July 2007 -
(CC) EBM WebSourcing - This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/
PEtALS Developers' Guide
Table of Contents
1. Building PEtALS from source ............................................................................................................... 5 1.1. Pre-Requisites .......................................................................................................................... 5 1.2. Checkout the sources ................................................................................................................. 5 1.3. Compiling PEtALS modules ....................................................................................................... 5 1.4. Assembling PEtALS modules ...................................................................................................... 6 1.4.1. Standalone server ........................................................................................................... 6 1.4.2. Component framework .................................................................................................... 7 1.4.3. Web application ............................................................................................................. 7 1.5. Compiling PEtALS Eclipse Plugins .............................................................................................. 7 2. PEtALS Coding Rules ........................................................................................................................ 12 2.1. Formatting rules ...................................................................................................................... 12 2.2. Naming conventions ................................................................................................................ 13 2.2.1. JBI artifacts ................................................................................................................. 13 2.3. How to ... .............................................................................................................................. 13 2.3.1. How to escape a warning detected by Findbugs .................................................................. 13 3. Developing under Eclipse .................................................................................................................... 14 3.1. Tools and plugins .................................................................................................................... 14 3.2. Preparing eclipse ..................................................................................................................... 14 3.2.1. Multiple workspaces ...................................................................................................... 14 3.2.2. Maven classpath variables .............................................................................................. 15 3.2.3. Selecting the JDK and its options .................................................................................... 16 3.2.4. Multiple workspaces building .......................................................................................... 17 3.2.5. Use the good source code formatter ................................................................................. 17 3.2.6. Use the good configuration of the source code reviewer tools ................................................ 21 3.3. Working on PEtALS projects .................................................................................................... 28 3.3.1. Importing project .......................................................................................................... 28 3.3.2. Create a PEtALS launcher .............................................................................................. 30 4. Using maven ..................................................................................................................................... 33 4.1. Creating a new module ............................................................................................................ 33 4.2. Creating new projects .............................................................................................................. 33 4.2.1. Creating a Binding Component ....................................................................................... 33 4.2.2. Creating a Service Engine .............................................................................................. 33 4.2.3. Creating a service unit ................................................................................................... 33 4.2.4. Creating a service assembly ............................................................................................ 33 4.3. Deploying artefacts to repositories .............................................................................................. 33 4.3.1. Deploying a POM ......................................................................................................... 33 4.3.2. Deploying a JAR .......................................................................................................... 33 4.3.3. Deploying a source JAR ................................................................................................ 34 5. Releasing PEtALS ............................................................................................................................. 35 5.1. Releasing a module ................................................................................................................. 35 5.1.1. Preparing the release ..................................................................................................... 35 5.1.2. Performing the release ................................................................................................... 35 5.2. Releasing a POM file ............................................................................................................... 35 5.3. Maintenance Release ................................................................................................................ 36 6. Remote debugging with PEtALS .......................................................................................................... 37 6.1. Debuging with Eclipse ............................................................................................................. 37 6.1.1. Run PEtALS ................................................................................................................ 37 6.1.2. Attach Eclipse IDE to PEtALS ........................................................................................ 37 7. Profiling with PEtALS ........................................................................................................................ 39 7.1. Profiling with NetBeans ........................................................................................................... 39 7.1.1. Profiler Agent installation ............................................................................................... 39 7.1.2. Run PEtALS ................................................................................................................ 39 7.1.3. Attach NetBeans IDE to PEtALS ..................................................................................... 39 8. Best practices .................................................................................................................................... 49 8.1. Managing bugs and feature requests ........................................................................................... 49
PEtALS Developers' Guide
2
PEtALS Developers' Guide
8.1.1. Bugs ........................................................................................................................... 49 8.1.2. Features ...................................................................................................................... 49
PEtALS Developers' Guide
3
PEtALS Developers' Guide
List of Figures
3.1. 3.2. 3.3. 3.4. 3.5. 3.6. 3.7. 3.8. 3.9. Eclipse prompt at startup .................................................................................................................. Eclipse classpath variables ................................................................................................................ Define M2_REPO variable ............................................................................................................... Choosing Java Development Kit ........................................................................................................ Import projects into Eclipse .............................................................................................................. PEtALS projects in Eclipse ............................................................................................................... Run main window ........................................................................................................................... Select server library ......................................................................................................................... Define PEtALS arguments ................................................................................................................ 14 15 16 16 29 30 30 31 32
PEtALS Developers' Guide
4
Building PEtALS from source
Chapter 1. Building PEtALS from source
1.1. Pre-Requisites
To be able to get the sources and build PEtALS, you must install the following tools : • JDK 1.5.X : PEtALS is developed using java 5 features. You need to install a JDK 1.5.x to be abble to compile PEtALS. • Maven : We use the Apache maven project to build PEtALS. Maven can be downloaded here : http://maven.apache.org/ download.html. • svn : A subversion client is required to work with the project sources. We suppose that all the required binaries (mvn, java, javac, svn) are defined in you path.
1.2. Checkout the sources
The PEtALS sources are hosted by the ObjectWeb forge. As developer you can checkout the sources from the repository with a svn client. • Checking out the sources as anonymous user : svn checkout svn://svn.forge.objectweb.org/svnroot/petals/trunk petals • To check out the sources as developer, you must be registered in the ObjectWeb forge and be activated as PEtALS developers (contact the project administrator to get authorization) : svn checkout svn+ssh://@svn.forge.objectweb.org/svnroot/petals/trunk petals These two commands will check out the sources into the petals directory.
1.3. Compiling PEtALS modules
Since the compilation uses lots of memory, you must define specific system variables for maven. On a Linux system : MAVEN_OPTS=-Xmx512m export MAVEN_OPTS
Note
You can define this variable in your .bashrc file. In order to retrieve all the artifacts, you must add specific configuration to Maven. To do so, add a settings.xml file in your local Maven repository (~/.m2/ under Linux).
default-profile TRUE objectweb-release
PEtALS Developers' Guide
5
Building PEtALS from source
Objectweb Repo http://maven.objectweb.org/maven2 false true objectweb-snapshot Objectweb SNAPSHOT Repo http://maven.objectweb.org/maven2-snapshot true false objectweb-plugin Objectweb plugin Repo http://maven.objectweb.org/maven2 false true
You can dowload the settings.xml file here. Now that all is ready, you can compile the sources: 1. Go into the sources directory cd petals 2. Build the required dependencies first mvn -Denv=first 3. Build petals mvn Note that you can skip all the unit tests like this (generation will be faster...) mvn -Dmaven.test.skip
1.4. Assembling PEtALS modules
Now that all the PEtALS artefacts are compiled, you can build various PEtALS distributions.
1.4.1. Standalone server
To create the standalone version of PEtALS:
PEtALS Developers' Guide
6
Building PEtALS from source
1. Go into the standalone directory cd petals/petals-platform/petals-standalone mvn assembly:assembly 2. The standalone version of PEtALS is the available in the target repository cd target/target/petals-standalone-$VERSION-SNAPSHOT-dev.dir/petals-standalone-$VERSIONSNAPSHOT where $VERSION is the current version of the standalone project. Note that archive files are generated too.
1.4.2. Component framework
The component development kit can be packaged with the maven assembly plugin: cd petals/petals-cdk mvn assembly:assembly The assembly command will generate an archive file with all the required java libraries.
1.4.3. Web application
PEtALS is also available as web application in order to be embedded in web application containers.
1.4.3.1. JONAS 1.4.3.2. JBOSS 1.4.3.3. SIMPLE WEB APPLICATION
1.5. Compiling PEtALS Eclipse Plugins
Waiting a Maven2 build to build PEtALS Eclipse plugins, the build/assembly/packaging of PEtALS Eclipse plugins is manual: • Start Eclipse and Import all Petals Eclipse plugins projects:
PEtALS Developers' Guide
7
Building PEtALS from source
• Open the project "org.objectweb.petals.tools.plugin.update":
• Open the file "site.xml":
PEtALS Developers' Guide
8
Building PEtALS from source
• Click on the button "Build All":
• Export the build result in a zip file "org.objectweb.petals.tools.plugin.update":
using
the
contextual
menu
"Export..."
on
the
project
PEtALS Developers' Guide
9
Building PEtALS from source
• Select your export type "Archive File":
PEtALS Developers' Guide
10
Building PEtALS from source
In the left area, select the project "org.objectweb.petals.tools.plugin.update". In the right area, unselect the file ".project". Enter you archive file name. And click on "Finish" to build the archive file containing the Eclipse site update to install the PEtALS Eclipse plugins.
PEtALS Developers' Guide
11
PEtALS Coding Rules
Chapter 2. PEtALS Coding Rules
All PEtALS source code must respect some coding rules: • formatting rules, • naming conventions, • coding rules. These rules are verified automatically by the tools: Checkstyle, PMD and Findbugs.
2.1. Formatting rules
PEtALS formating rules are designed to format all the code according to the Java Sun code style recommandation with some little changes to match the PEtALS configuration of Checkstyle, PMD and Findbugs. Thess rules are the following: • class members sorting rule: • Inside a class, member must be sorted by category in the following order: 1. types, 2. static fields, 3. fields, 4. constructors 5. static initializers, 6. static methods 7. initializers, 8. methods. • Inside a category, members must be sorted by visibility in the following order: 1. public, 2. protected, 3. default, 4. private. • import statements sorting rule: they are ordered as: 1. java 2. javax 3. org 4. org.objectweb.petals 5. com PEtALS Developers' Guide
12
PEtALS Coding Rules
2.2. Naming conventions
2.2.1. JBI artifacts
2.2.1.1. Components
• The binding components should be named petals-bc-* • The service engines should be named petals-se-*
2.2.1.2. Service units, assemblies and shared libraries
• The service units should ne named su-*-consume or su-*-provide • The service assemblies should be named sa-* • The shared libraries should be named sl-*
2.3. How to ...
2.3.1. How to escape a warning detected by Findbugs
A warning detected by Findbugs, that can't be fixed for a good reason, can be escaped using the following findbugs annotation: edu.umd.cs.findbugs.annotations.SuppressWarnings. More information on this annotation could be found here. The two parameters of the annotation must be provided. To use this annotation, you must add the findbugs annotations artefact to the project POM file with a scope set to provided:
... findbugs annotations 1.0.0 provided ...
Next, you can add the annotation without to provide a justification, as following:
@edu.umd.cs.findbugs.annotations.SuppressWarnings(value={"UI"}, justification="Will be never extended.") public void setUp() { ... }
PEtALS Developers' Guide
13
Developing under Eclipse
Chapter 3. Developing under Eclipse
This chapter talks about how to configure and use the eclipse IDE to develop PEtALS.
3.1. Tools and plugins
You can download the eclipse IDE on the eclipse website (http://www.eclipse.org). Additionaly you have to install these plugins (Please refer to the plugins web sites for installation): • Subclipse : Used for source code management under SVN • Checktyle : Used to check that your code is clean • PMD : • Findbugs : • Web tools platform
3.2. Preparing eclipse
3.2.1. Multiple workspaces
The first thing you must know is getting work with multiple workspaces in Eclipse. For developers a workspace is a collection of related projects. You can have more than one workspace for different sets of projects. In almost cases the best way to manage these multiple workspaces is configuring Eclipse to prompt which workspace to use every startup (otherwise, you should create various copies of Eclipse start icon/link on your desktop using the -data as an executable argument to specify your choice). To configure this option in Eclipse you must access Window -> Preferences..., then select General -> Startup and Shutdown item in the navigable tree and check the box for Prompt for workspace on startup - if not set. You will be prompted to select a workspace in the next time you start Eclipse.
Figure 3.1. Eclipse prompt at startup
PEtALS Developers' Guide
14
Developing under Eclipse
If the specified path does not exist Eclipse will try create the directory. You can change the workspace while Eclipse is already running (File - Switch Workspace... submenu). Be aware that a workspace is more than a collection of projects. Eclipse internally uses the workspace directory to store your preferences for that set of projects - and other runtime files and views. In each workspace you can have specific configurations, for example: code formatting, code comments templates, JRE used, so on... Separating the workspace directory tree from project directory tree is a good approach for better management. That way you are able to share project among various workspaces. At least you can avoid unexpected projects removal when installing a new version of Eclipse.
3.2.2. Maven classpath variables
When a Maven project is imported into Eclipse it expects a M2_REPO classpath variable entry. This variable is used to reference project libraries within your local Maven repository. To setup this variable go to Window -> Preferences... and select Java -> Build Path -> Classpath Variables on the navigable tree.
Figure 3.2. Eclipse classpath variables
Add a new M2_REPO entry pointing to the local Maven 2 repository (Under Linux, it is generally : M2_REPO=~/.m2/ repository).
PEtALS Developers' Guide
15
Developing under Eclipse
Figure 3.3. Define M2_REPO variable
3.2.3. Selecting the JDK and its options
Eclipse allow a number of installed JRE/JDK configured in your environment. In this case, you can easily use other java runtime by accessing Window -> Preferences and then selecting the Java -> Installed JREs on the navigable tree. For PEtALS, choose a ''Java(TM) 1.5'' compatible JDK.
Figure 3.4. Choosing Java Development Kit
PEtALS Developers' Guide
16
Developing under Eclipse
3.2.4. Multiple workspaces building
The Maven Eclipse plugin is used to create eclipse projects from the PEtALS modules: mvn eclipse:eclipse This command will generate Eclipse project required files (.project,.classpath, .checkstyle...) wich will be used for project imports. It will also dowload all the projects required sources from Maven repositories.
Note
Generating all projects from the root path takes a lot of time
3.2.5. Use the good source code formatter
A part of the PEtALS source code formating rules are described in a file to used with Eclipse. To import the formatter, you have to: • go to Window -> Preferences , then select Java -> Code Style -> Formatter:
• click on "Import", and select the file "petals-formatter.xml" from the directory quality/src/main/resources of the PEtALS project:
/petals-
PEtALS Developers' Guide
17
Developing under Eclipse
• click on "Apply" to save. The import statements ordering rules are set from a file: • go to Window -> Preferences , then select Java -> Code Style -> Organize Imports:
PEtALS Developers' Guide
18
Developing under Eclipse
• click on "Import", and select the file "eclipse.importorder" in the directory /petals-quality/ src/main/resources of the PEtALS project:
PEtALS Developers' Guide
19
Developing under Eclipse
• click on "Apply" to save. The class members ordering rules must be set manualy: • go to Window -> Preferences , then select Java -> Appearance -> Members Sort Order:
PEtALS Developers' Guide
20
Developing under Eclipse
• use buttons "Up" and "Down" to have the same ordering as the previous screenshot. • click on "OK" to save. Now you can format all the code you write by doing a right click on the java file and selecting Source -> Format.
3.2.6. Use the good configuration of the source code reviewer tools
PEtALS provides configuration for Checkstyle, PMD, and use the default one for Findbugs. First, the associated Eclipse plugins must be installed.
3.2.6.1. Configuration of PMD
The PMD configuration is generated during the Eclipse project creation when using the maven-eclipse-plugin from the command-line. The plugin PMD is configured at Eclipse workbench level: • go to Window -> Preferences , then select PMD -> Rules configuration:
PEtALS Developers' Guide
21
Developing under Eclipse
• click on "Remove all" to remove all rules:
• click on "Import" to import PEtALS rules:
PEtALS Developers' Guide
22
Developing under Eclipse
Click on "Browse" and select the file "pmd.xml" in the directory resources of the PEtALS project: • click on "OK":
/petals-quality/src/main/
• click on "OK" to save the PMD rules.
3.2.6.2. Configuration of Checkstyle
The Checkstyle configuration is generated during the Eclipse project creation when using the maven-eclipse-plugin from the command-line. The plugin Checkstyle is configured at a Eclipse project level : • on a selected project, from the contextual menu, go to Properties -> Checkstyle, next select the tab "local checkstyle configuration":
PEtALS Developers' Guide
23
Developing under Eclipse
• click on "New":
PEtALS Developers' Guide
24
Developing under Eclipse
Select an external configuration, set its name, and use the file "checkstyle.xml" in the directory / petals-quality/src/main/resources of PEtALS. • click on "OK":
PEtALS Developers' Guide
25
Developing under Eclipse
• go on the tab "General":
Select the previously created configuration, and activated Checkstyle on the project. • click on "OK" to save the Checkstyle configuration for the project.
PEtALS Developers' Guide
26
Developing under Eclipse
3.2.6.3. Configuration of Findbugs
The plugin Findbugs is configured at the Eclipse project level : • on a selected project, from the contextual menu, go to Properties -> Findbugs, next select the tab "General":
Set the priority to "Low", and activated Findbugs. • go to the tab "Extended":
PEtALS Developers' Guide
27
Developing under Eclipse
Set the effort to "Maximal". • click on "OK" to save the Findbugs configuration for the project.
3.3. Working on PEtALS projects
3.3.1. Importing project
To import a generated Eclipse project in Eclipse, go to File -> Import -> Existing Projects into Workspace command. You can choose to import all PEtALS projects by selecting the root folder of the PEtALS project or just some of them by selecting a sub folder.
PEtALS Developers' Guide
28
Developing under Eclipse
Figure 3.5. Import projects into Eclipse
Once required projects selected, you should see them in your workspace :
PEtALS Developers' Guide
29
Developing under Eclipse
Figure 3.6. PEtALS projects in Eclipse
3.3.2. Create a PEtALS launcher
The next configuration you need to create is a Server Launch configuration that runs as a local application. From the menu, select Run -> Run.... In the wizard, select "Java Application" and hit "New" to create a launch configuration named Petals - Server. For project choose: petals-standalone and for main class enter:
org.objectweb.petals.system.launch.StandaloneLauncher
Figure 3.7. Run main window
PEtALS Developers' Guide
30
Developing under Eclipse
Select the Classpath tab. Select "Add Jars..." to be added to the User Entries list. Add the server library wich is located under the target direcotry of your petals-standalone project (/petals-standalone/target/petals-standalone-X.XSNAPSHOT-dev.dir/petals-X.X-SNAPSHOT/bin).
Figure 3.8. Select server library
You can also define the PEtALS standalone arguments. For example, if you want PEtALS starts in console mode, add the -console argument.
PEtALS Developers' Guide
31
Developing under Eclipse
Figure 3.9. Define PEtALS arguments
PEtALS Developers' Guide
32
Using maven
Chapter 4. Using maven
4.1. Creating a new module
mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes -DgroupId=org.objectweb.petals DartifactId=
4.2. Creating new projects
4.2.1. Creating a Binding Component
The following command will create a new binding component project with the required files and directory structure : mvn archetype:create -DarchetypeGroupId=org.objectweb.petals -DarchetypeArtifactId=maven-archetypepetals-jbi-binding-component -DarchetypeVersion=1.0.0 -DgroupId=org.objectweb.petals -DartifactId= -Dversion=1.0-SNAPSHOT
4.2.2. Creating a Service Engine
The following command will create a new service engine project with the required files and directory structure : mvn archetype:create -DarchetypeGroupId=org.objectweb.petals -DarchetypeArtifactId=maven-archetypepetals-jbi-service-engine -DarchetypeVersion=1.0.0 -DgroupId=org.objectweb.petals -DartifactId= -Dversion=1.0-SNAPSHOT
4.2.3. Creating a service unit
The following command will create a new service unit project with the required files and directory structure : mvn archetype:create -DarchetypeGroupId=org.objectweb.petals -DarchetypeArtifactId=maven-archetypepetals-jbi-service-unit -DarchetypeVersion=1.0.1 -DgroupId=org.objectweb.petals -DartifactId= -Dversion=1.0-SNAPSHOT
4.2.4. Creating a service assembly
The following command will create a new service assembly project with the required files and directory structure : mvn archetype:create -DarchetypeGroupId=org.objectweb.petals -DarchetypeArtifactId=maven-archetypepetals-jbi-service-assembly -DarchetypeVersion=1.0.0 -DgroupId=org.objectweb.petals -DartifactId= -Dversion=1.0-SNAPSHOT
4.3. Deploying artefacts to repositories
4.3.1. Deploying a POM
mvn -N deploy:deploy-file -DrepositoryId=objectweb -Durl=scp://jupiter.objectweb.org:/var/lib/gforge/chroot/ home/groups/maven/htdocs/maven2 -DpomFile=pom.xml -Dfile=pom.xml The -N option stands for non-recursive deployment, it will deploy only the specified file.
4.3.2. Deploying a JAR
mvn -N deploy:deploy-file -DrepositoryId=objectweb -Durl=scp://jupiter.objectweb.org:/var/lib/gforge/chroot/ home/groups/maven/htdocs/maven2 -DpomFile=pom.xml -Dfile=.jar
PEtALS Developers' Guide
33
Using maven
4.3.3. Deploying a source JAR
Same as previous with -Dclassifier=sources option.
PEtALS Developers' Guide
34
Releasing PEtALS
Chapter 5. Releasing PEtALS
5.1. Releasing a module
We use the Maven release plugin to release petals modules.
5.1.1. Preparing the release
mvn release:prepare -Denv=release -Dscm.username= The previous command will execute: 1. Check that there are no uncommitted changes in the sources 2. Check that there are no SNAPSHOT dependencies 3. Change the version in the poms from x-SNAPSHOT to a new version (you will be prompted for the versions to use) 4. Transform the SCM information in the POM to include the final destination of the tag 5. Run the project tests against the modified POMs to confirm everything is in working order 6. Commit the modified POMs 7. Tag the code in the SCM with a version name (this will be prompted for) 8. Bump the version in the POMs to a new value y-SNAPSHOT (these values will also be prompted for) 9. Commit the modified POMs You must provide : • The -Denv=release option to generate optimized classes • Your objectweb developer name that will be used for scm connection and in generated POM files
5.1.2. Performing the release
mvn release:perform -Denv=release This command will execute : 1. Checkout from an SCM URL with optional tag 2. Run the predefined Maven goals to release the project (by default, deploy site-deploy) You can get additional information on the release plugin page: http://maven.apache.org/plugins/maven-release-plugin/.
5.2. Releasing a POM file
To release a single file (like a Maven POM file), follow these steps: 1. Change the POM version from SNAPSHOT to non SNAPSHOT. For example, if the current version is '2-SNAPSHOT', the new version will be '2'. 2. Check that there are no SNAPSHOT dependencies in the POM file. 3. Commit modified the POM file.
PEtALS Developers' Guide
35
Releasing PEtALS
4. Tag this new POM file. If the artifactId is 'petals-module' and its version is '2', create a tag named 'petals-module-2' and put the POM file in this tag directory. 5. Change the POM version to next release iteration ('3-SNAPSHOT' for the current example). 6. Checkout the previously created tag from the SCM 7. Deploy the POM file to the maven repository: mvn -N deploy:deploy-file -DrepositoryId=objectweb -Durl=scp://jupiter.objectweb.org:/var/lib/gforge/chroot/ home/groups/maven/htdocs/maven2 -DpomFile=pom.xml -Dfile=pom.xml
5.3. Maintenance Release
When a module is released, a new tag is created under the tags SCM directory. For example, when the petals-componentframework v 2.0 module is released, the tags/petals-component-framework-2.0 directory is created under the SCM. This tag MUST be used to create a branch for maintenance. The maintenance branch should have the same name as the tag one. Once the branch is created, you have to modify the pom.xml file : • Set the version as maintenance SNAPSHOT. For example, a 2.0 version becomes 2.0.1-SNAPSHOT • Modify the SCM attributes. The maven release plugin has created SCM elements for the previously created tag. You have to change the URL to be the branch one. You can now checkout the branch, and work on it as usual. The release process is the same as the trunk modules one.
PEtALS Developers' Guide
36
Remote debugging with PEtALS
Chapter 6. Remote debugging with PEtALS
This chapter describes how to debug a remote PEtALS instance.
6.1. Debuging with Eclipse
This section describes how to debug a remote PEtALS instance using Eclipse 3.3.
6.1.1. Run PEtALS
• PEtALS must be started in debug mode:
$PETALS_HOME/bin/debug.sh -d
6.1.2. Attach Eclipse IDE to PEtALS
• Start Eclipse IDE • Launch the Debug Wizard (menu Run/Open Debug Dialog...):
• Create a new Remote Java Application, using the contextual menu on "Remote Java Application":
PEtALS Developers' Guide
37
Remote debugging with PEtALS
Select "Standard" as connection Type, set your host, set 8000 as port number. It is possible to set "petals-kernel" as source project, and add other sources in the tab "Source". • Launch the debug clicking on "Debug". Now, you can play with PEtALS.
PEtALS Developers' Guide
38
Profiling with PEtALS
Chapter 7. Profiling with PEtALS
This chapter describes how to profile a PEtALS instance. You could profile a PEtALS instance to optimize the NMR, components or services.
7.1. Profiling with NetBeans
This chapter describes how to profile a PEtALS instance using NetBeans 5.5.1.
7.1.1. Profiler Agent installation
• Download the profiler remote pack corrsponding to your system, • Unpack the downloaded archive on remote machine:
mkdir nb-profiler-server cd nb-profiler-server unzip ../profiler-server-551-linux-15.zip
• Run the calibration:
cd bin ./calibrate.sh
7.1.2. Run PEtALS
• PEtALS must be started in profiling mode:
$PETALS_HOME/bin/debug.sh -P netbeans
7.1.3. Attach NetBeans IDE to PEtALS
• Start NetBeans IDE • Launch the attach profiler wizard (menu Profile/Attach Profiler...), select "Analyze Performance":
PEtALS Developers' Guide
39
Profiling with PEtALS
• Select "Entire Application" and "Exclude Java Core Classes". Click on "Customize Filter":
PEtALS Developers' Guide
40
Profiling with PEtALS
• To defined a PEtALS global filter, click on "Edit Global Filters":
PEtALS Developers' Guide
41
Profiling with PEtALS
• Click on "New" to add the PEtALS global filter:
PEtALS Developers' Guide
42
Profiling with PEtALS
• Click on "Edit" to defined filter:
PEtALS Developers' Guide
43
Profiling with PEtALS
Set the value to: "org.objectweb.petals.", don't forget the last dot. • Click on "OK" to save the new global filter. • Click on "Add" to define a new filter set:
PEtALS Developers' Guide
44
Profiling with PEtALS
Set its name to "Exclude extra classes for PEtALS", set its type to "Exclusive", and select the following filters: • Apache.org classes, • W3C.org classes, • XML.org classes • Click on "Add" to define a new filter set:
PEtALS Developers' Guide
45
Profiling with PEtALS
Set its name to "Include PEtALS classes", set its type to "Inclusive", and select the filter "PEtALS classes". • Click on "OK" to save the configuration. • Click on "Attach Wizard" to defined the remote PEtALS instance:
PEtALS Developers' Guide
46
Profiling with PEtALS
• Select "Application", and click on "Next":
• Select "Remote", and set the correct values in fields "Hostname" and "Host OS", and click "Next":
PEtALS Developers' Guide
47
Profiling with PEtALS
• Click on "Finish". • Click on "Attach" to start the profiling. Now, you can play with PEtALS.
PEtALS Developers' Guide
48
Best practices
Chapter 8. Best practices
8.1. Managing bugs and feature requests
8.1.1. Bugs
• When a bug is created; the category, summary and description fields must contain relevant information to unterderstand the bug. The GROUP field has to match the component version where the bug is found. • The PEtALS leader set the priority and affect a developer to the task. The correction starts here. • When the bug is corrected, the developer set the RESOLUTION field to FIXED. Moreover, he set the STATE field to PENDING. • When a release occurs for this component, the PEtALS leader set the STATE field to CLOSED and the version of the component is set as a comment.
8.1.2. Features
• When a feature is created; the category, summary and description fields must contain relevant information to unterderstand the feature. The GROUP field remains empty. • The Petals leader evaluates the request and, if accepted, sets a priority. • The Petals leader affects a developer to the task. The implementation starts here. • When the feature is implemented, the developer sets the STATE field to PENDING. • When a release occurs for this component, the PEtALS leader sets the STATE field to CLOSED and the GROUP field is set with the version where the feature can be found.
PEtALS Developers' Guide
49