Glassfish OSGi-JavaEE Part2 : Building a Fighterfish's Environment
In the Part1 , I introduced Glassfish OSGi-JavaEE and Fighterfish , simply saying, Fighterfish is the implementation of Glassfish OSGi-JavaEE. In addition, I also introduced how to build Fighterfish modules from its trunk.
In the Part2, I will tell you how to build a fighterfish's development env including debugging, at the same time, I will also tell you how to contribute a patch for a fighterfish's module successfully. The part will benifit to those guys who are interested in Glassfish OSGi-JavaEE and have a plan to contribute the field.
1. How to build a fighterfish's development env with eclipse and maven
If you are a NetBeans or IntelliJ IDEA fans, I am sorry that the following contents maybe disappointed you, because I have been always using Eclipse.
prerequisite: needing the following tools
1） Eclipse Indigo or other versions
2) Maven 3.0.4
Note: I suggest you do not use m2e plugin, because once you use the plugin, maybe you will meet some curious problems while you import fighterfish modules into Eclipse and try to build them.
Now, let us try to build a development envirioment.
[Step1] Building fighterfish's modules
Please according to Part1 , first we need to do a build for fighterfish's modules. Although you can ignore the step, I suggest you do it , for example, maybe there is a scene as following:
I wish to contribute and update osgi-web-container module which depends on osgi-javaee-base 1.0.0, if you need not to update osgi-javaee-base, you can ignore the step, however, if you also need to update osgi-javaee-base, first you must build osgi-javaee-base, then you need to modify osgi-web-container's pom and set osgi-javaee-base dependency version into 1.0.6-SNAPSHOT.
[Step2] associating maven with eclipse
Because we use maven to manage dependencies , we must make eclipse workspace to recognise maven, here, there are two ways:
1) manually add M2_REPO into Eclipse( Preferences→ Java → Build Path → ClassPath Variables)
2)executing the following command from your shell
mvn -Declipse.workspace=<Your workspace> eclipse:add-maven-repo
[Step3] generating eclipse related project file and classpath file
This is a very critical step used for importing a fighterfish's module.
Entering the fighterfish/module or some module of fighterfish/module, Executing the following command from your shell,
[Step4] importing a fighterfish module into eclipse
If Step3 is successful, you can open eclipse and import a fighterfish module into eclipse. The following is a sample(osgi-javaee-base) from my eclipse env.
[Step5] building the imported fighterfish module
Once finishing step4, you can programe java codes and elaborate your ability and wisdom！ However, if you want to build an artifact of the module, you still need to go back your shell and execute "mvn clean install". Maybe you think that it is not inconvenientable compared with other maven eclipse plugin(eg. m2e), however, I think this can be acceptable , :).
2. How to debug a fighterfish's module in eclipse
If you obey with 1, you should toword a success road to contribute. Then, you will meet a problem : how I can debug a fighterfish's module , especially while I am resolving a bug from some fighterfish's module?
It is a good question!
The question is also related to how to debug glassfish itself. Basically, this needs to divide two scene as following,
1) debugging fighterfish module after starting glassfish domain
The scene is a normal case and you only need to do the following:
executing "asadmin start-domain --debug"
This will make glassfish listen 9009(default port) port in a unsuspend way, then, you create a remote debug configuration in eclipse and attach the 9009 port. It is very simple!
2) debugging fighterfish module starting logic while starting glassfish domain
Firstly, you need to config domain.xml and find the following line:
<java-config debug-options="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9009" system-classpath="" classpath-suffix="">
and, modify "suspend=n" into "suspend=y".
then, executing "asadmin start-domain --debug",
finally, you create a remote debug configuration in eclipse and attach the 9009 port.
Now, you can start the travle of debugging fighterfish and before debugging, you can add related project's source into eclipse and attach these project's source into the remote debug configuration because this will be very convenientable while debugging.
3. How to contribute a patch for a fighterfish's module successfully
Now, I have been one of glassfish team's developers and looking back the past contribution, I have much thought, and in this part, I want to tell you the most important thing→"How to contribute a patch for a fighterfish's module successfully" if you want to aim to be a developer of glassfish team or wish your patch can be acceptable more quickly.
Here, we need to do several things,
1) re-produce the scene of this bug or feature or task
re-producing the scene of this bug or feature or task from glassfish jira as possible, and noting that if you have found and confirmed a new bug or have an outstanding idea about some module, you can file a jira issue in glassfish jira . If being the latter , you must write re-producing steps carefully because this will be very important for other people of community.
2) finding the reason, and you'd better do a initial of detailed investigation
If you have more time and aim to resolve the issue yourself, I wish you can do a detaild investigation. Frankly speaking, the investigation is my best love because while I start to do an investigation, I felt that I am a detective and try to find each useable glue for the issue's true reason and fixing method.
3) try to fix the issue and supply a patch
Based on 2), you can try to fix the issue and supply a patch, here, there are some experience to share with you. Because fighterfish is a matured project, and most modules use some same design patterns(I will introduce you in next articles), you'd better stick to these design guidelines and not re-invent a new wheel! At the same time, I wish you can stick to some programming rules , and this is not very difficult because you can do it by seeing existed sources carefully.
Noting that because currently, glassfish jira is in updating and does not allow uploading any attachment, if you have a patch, please send it into email@example.com or firstname.lastname@example.org (Sahoo is fighterfish's leader), of course, you can also send it to me, :)
4) modify your patch based on community's review
Normally, you will receive a patch's review result, and you need to modify your patch until it is no any problem. Please remembering not to foget adding comments and modifying copyright. Here, I need to say a point about copyright and I have ever made a mistake.
For example, the original file has a copyright as following:
* Copyright (c) 2012 Oracle and/or its affiliates. All rights reserved.
While you modify the file, you should modify the above copyright into the following:
* Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
★I have ever made a mistake as following:
* Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
5) doing a fighterfish it test
This step is the most critical step of above steps, because fighterfish it test is to protect your patch from casuing some regression, how to do it?
Firstly, entering fighterfish/test directory from your shell, and executing the following command to build util and app modules(note, you also need to build fighterfish/sample because fighterfish it test needs some samples's artifacts)
Secondly, entering fighterfish/it directory from your shell, and executing the following command
mvn clean test -Dglassfish.home=/.../.../glassfish4/glassfish
Here, glassfish.home property must be set to specify a valid glassfish distro, if you am doing a patch for some fighterfish patch, you must first put artifact of the fighterfish module with your patch into /.../.../glassfish4/glassfish/modules/autostart to override the original artifact, then execute the above test command.
In the next parts, I will start to share you with Glassfish OSGi-JavaEE's important features and new features brought into current v4, and look into fighterfish in depth.