Resin for Eclipse 0.8.2
Documentation

0. What's new in version 0.8.2 ?
1. Introduction
2. Requirements
3. Installing
4. Resin management
    4.1 Setting preferences
    4.2 The RFE project and server's descriptions
    4.3 Opening the Resin view
    4.4 Using
    4.5 Reloading
    4.6 Working with hot code replace
    4.7 HTTPS
    4.8.Debugging
5. Web projects
    5.1 Description
    5.2 Setting preferences
    5.3 Creating generic projects
    5.4 Creating "Optimized for Resin" projects
    5.5 JSP Debugging (only available for Resin Web projects)
6. War exporation
    6.1 limitations
    6.2 Using
7. Problems
8. History
9. To do
10. Known limitations
11. Recommanded plugins
12. Feedback
13. Post Scriptum

0. What's new in version 0.8.2 ?

• Two minor bugs corrected

1. Introduction
Welcome to the "Resin for Eclipse" plugin version 0.8.2.

Resin is a great Servlets and JSP application Server (if you want to know more about this server please go to http://www.caucho.com)
I use WSAD 5 for development and I think that server plugins that come with have several problems for Servlets and JSP :

• Websphere 4 and 5 are slow for launching or compiling JSPs.
• Websphere 5 express is much faster for compiling JSPs but is still slow for launching.
• Tomcat is fast but has several lacks of reloading.

At my sense and from my little experience, I can say that Resin is very fast (maybe the fastest) and has lots of reloading capabilities, it's a great server for development (it may also be very good for production purposes).

This plugin includes three main features :

• Resin management : a graphical user interface to manage Resin Servers within Eclipse : you can create servers, add web projects, edit classpath and system properties, manage https, launch, debug and stop server,..... It should work with any type of web projects created by any other plugin : Web projects that come with WSAD for example.
• Web projects : a wizard to create web projects.
• War exportation : a wizard to export web projects into War files.

2. Requirements
To make the Resin management feature run you need Resin Sever : you can download it at http://www.caucho.com
You also need to install a JDK : 1.3.1, 1.4.0 or 1.4.1 but you don't need to register it into Eclipse.
I strongly recommend you to use JDK1.4.1(contains JSSE, HTTPS faster to launch, hot code replace).
If you plan to use HTTPS :

• With JDK 1.3.1 : you must download JSSE at http://java.sun.com/products/jsse/. Copy "jcert.jar", "jnet.jar" and "jsse.jar" included in the jsse archive into your"JDK1.3.1_HOME/jre/lib/ext" directory.
• With JDK 1.4.0 or 1.4.1 : you have nothing to do, JSSE is already included.

This plugin has been tested with Resin 2.1.4 and 2.1.6 on Windows XP and Windows NT4 SP6 on Eclipse 2.0.2, 2.1(RC2) and WSAD 5.
It should work on any other platform but I don't have a way to test it. If you encounter problems with your platform see the problems section.

3. Installing
Remove any older version and copy the "fr.helloworld.eclipse.resin_0.8.2" directory into your plugins directory.
If you plan to create generic web projects or want that the "jsdk23.jar" library included in "Optimized for Resin" web projects contains sources, you need to install "J2EE Libraries" plugin wich is downloadable from the web site. To install it, copy "j2ee.libraries_1.0.0" into your plugins directory.

4. Resin management

4.1 Setting preferences
You should set the preferences first.
Go to Windows -> preferences -> Resin For Eclipse :

General Tab

• Resin home directory : the home of Resin.
• JDK home directory : select the JDK with which Resin will be launched.
• Extra VM parameters (optional) : lets you add VM parameters if you need it.
• Specify compiler path (optional) : select this option to set the compiler library if you need it. This option may be only useful for Mac OS users.
• Web roots directories : names of the directories within your project that could be the root of your web application : for example, WSAD creates a "Web Content" directory in web projects which is the root of the web application. You should let the default values.

Your preferences should look like this :

Advanced Tab
These options show you the list of ports used by the plugin (for an internal use), you can modify these values if you have ports conflicts.

4.2 The RFE project and server's descriptions
Server's descriptions are saved in the workspace in a simple project called "RFE".
This project will be automatically created.
A description is a XML file with a ".rsd"(Resin Server Description) extension.
Server's descriptions are not synchrone with their visual respresentation in the resin view, they are saved when you close Eclipse or when you choose "Server -> Save" in the menu.
Please do not edit ".rsd" files manually or do it at your own risks.
If you make changes to your ".rsd" file and want to display them, choose "Server -> Update" in the menu.
If you put new ".rsd" files into "RFE", choose "Server -> Find new servers" in the menu to display them.
RFE project may also contain Resin configuration files for your servers if you let the plugin generate them for you.

4.3 Opening the Resin view
Go to Window -> Show view -> other -> Resin For Eclipse-> Resin.
My preference is to put the view in the left bottom part of the screen in the Java perspective.



4.4 Using
Using is very easy and intuitive, you can access to all the functions with the right-click in the Resin view :



Menu : Server -> Create server
Create a new server..
If you let the "Generate default Resin .." option checked, a default configuration file will be created, it will be located in "RFE/Server_name.resinconf". If not, you must choose a configuration file in the workspace.
The server's description is saved in "RFE/Server_name.rsd".

Menu : Server -> Save
Save the selected server's to "RFE/Server_name.rsd".

Menu : Server -> update
Update the selected server with "RFE/Server_name.rsd" description.

Menu : Server -> Find new Servers
Find new ".rsd" files located in "RFE" and display new servers accordingly.

Menu : Sart
Start the selected server in run mode.

Menu : Debug
Start the selected server in debug mode.

Menu : Stop
Stop the selected server.

Menu : Restart
Depends on the selected item :

• Server : restart the selected server.
• Projects : restart the selected project.

Menu : Restart projects
Close and restart all the server's projects.

Menu : Edit
Depends on the selected item, (this function also works with double click) :

• Server : edit http port, enable https an define https port, select the "let me manage https" option, choose your Resin configuration file.
• *.resinconf : open a text editor with the server configuration file. You can edit all except default host webapps , http port and https(if the "let me manage https" option is not selected).
• Classpath : edit classpath that will be included in the server launch. Important : all jar files located in the RESIN_HOME/lib directory will be automatically loaded at launch.
• System properties : edit system properties that will be included in the server launch.
• System property : edit current system property
• Project : edit the root URI or edit its XML part that will be included into Resin configuration file at launch.

Menu : Delete
Delete the selected item.

Menu : Edit web projects
Edit Web projects.

A typical server started in debug mode should look like :

4.5 Reloading
While a server is active :
If you make changes to classpath, system properties, HTTP port or HTTPS, you have to restart the server.
If you make changes to the projects(add, remove or change root URIs), you only have to restart projects(magic no?).
If you make changes to a project Resin will automatically reload it.

4.6 Working with hot code replace
If you let Resin automatically detect changes in your project and then reload it, using hot code replace could become very difficult(in particular if you are working with sessions). To avoid auto-reloading, open your Resin configuration file and then edit the "<class-update-interval>" tag. Set the value to "-1". If you make changes to your project and want that Resin reloads it, just right click on it and choose "restart".

4.7 HTTPS
Well, I'm not an HTTPS expert. I've tried to include an easy way to include HTTPS using JSSE.
Be sure to have JSSE installed for your JDK before trying HTTPS mode.
If not, you will have an error while starting Resin.
If you are not satisfied with my management of HTTPS, you can select the "Let me manage HTTPS" option for the server and then edit the configuration file manually.

4.8 Debugging
To avoid being disturbed with classloaders or other internal server or JDK classes while debugging, I strongly recommend you to do this :
Go to Window -> Preferences -> Java -> Debug -> Step Filtering
Select the "Apply step filters to..." option.
Click on "Add filter"and then enter "com.caucho.*" then click on "Enable All".

It should look like this :

5. Web projects
You can create two different types of projects : generic or optimized for Resin.
Generic projects can be used without installing Resin, they should work on any application server.
Important : if you plan to create generic web projects, you need to install "J2EE Libraries" plugin wich is downloadable from the web site.
If you plan to debug JSPs on Resin and/or use libraries located in your "RESIN_HOME/lib" directory, use "Optimized for Resin" projects.
Important : if you want that the "jsdk23.jar" library included in "Optimized for Resin" web projects contains sources, you need to install "J2ee Libraries" plugin.

5.1 Description
Web projects are simply java projects with a particular structure :
Structure of a generic web project :


Structure of an "optimized for Resin" Web project :

The "RESIN_HOME" classpath variable is set when you set "Resin home directory" in preferences.
Please do not rename the "Web root" directory.
You will probably notice a strange thing : when you add a jar to the lib directory, you can see that it is added to the project's classpath(shotcut at the project's root) but you can't see it in the directory or when you delete a jar from the lib directory, the shorctut is still visible. Don't worry, it is an Eclipse bug (a bug is open), all works fine but the display is just "not synchronized", it seems to be corrected in 2.1(RC2).

5.2 Setting preferences
Set the preferences to choose the type of web projects that you want.
Go to Windows -> preferences -> Resin for Eclipse -> Web projects.
Your preferences should look like this :



If you choose generic web projects, please select the J2EE level :
J2EE 1.2 corresponds to servlets 2.2 and JSP 1.1 specifications, the "j2ee1.2.jar" is automatically added to the project's classpath.
J2EE 1.3 corresponds to servlets 2.3 and JSP 1.2 specifications, the "j2ee1.3.jar" is automatically added to the project's classpath.
Note that "j2ee1.2.jar" and "j2ee1.3.jar" contain sources.
If you choose "Optimized for Resin", you won't be able to select J2EE level.

5.3 Creating generic projects
Go to File -> New -> Web (RFE.) -> Web project (RFE is for "Resin For Eclipse", to avoid confusion with WSAD wizards)
Enter the project name then click on "Finish".

5.4 Creating "Optimized for Resin" projects
Go to File -> New -> Web (RFE) -> Web project. (RFE is for "Resin For Eclipse")
Enter the project name then click on "Next".
You can now select the librairies located in your "RESIN_HOME/lib" directory that you want to include in your project :



"resin.jar" and "jsdk23.jar" are automatically added, you can't remove them.

Do your choices and then click on "Finish".

5.5 JSP Debugging (only available for Resin Web projects)
Once your JSP is compiled (after the first call of your JSP) you must refresh the "Web root/WEB-INF/work" source folder.
You can now add breakpoints to the corresponding source.

6. War exportation
The plugin now includes a way to export web projects into War files.

6.1 Limitations
War exporation is only available for web projects that respect the following conditions :

• Source folder must not be the project itself.
• Web root directory must not be the project itself.
• Web root directory must be registred in preferences (Window -> Preferences -> Resin For Eclipse).

Web projects that come with this plugin and WSAD ones respect these conditions.

6.2 Using
Right click on your web project -> Export -> War file (RFE) (RFE is for "Resin For Eclipse").
It should look like this :



Options explained :

• Export sources : export all sources folders contained in the project into "WEB-INF/source"
• Overwrite file without warning : won't prompt you if the war file already exists.
• Compress : compress the war file.
• Remove Resin gene... : remove "WEB-INF/tmp" and "WEB-INF/work" folders and all Resin generated classes, this option is only useful if you run your project on Resin.

7. Problems
If you encounter any problem you can contact me. Please give me as much precision as possible in order to solve the problem.
If you have simply questions or suggestions don't hesitate to contact me.

My email : resinforeclipse@netcourrier.com in English or French

8. History

• 0.8.2
  • Two minor bugs corrected
• 0.8.1
  • Individual project restart improved : it is now a synchrone operation which does not touch the web.xml file anymore
  • A few improvements with war exporation
• 0.8.0
  • New preferences
  • Works with Eclipse 2.1(M4)
  • J2EE libraries for generic web projects now come in a separate plugin
  • Use of classpath variables in web projects
  • A few improvements with war exporation
• 0.7.0 :
  • servers descriptions are saved in the workspace in XML format
  • all dialogs have been rewritten
  • choose Resin configuration file for servers
  • edit XML description of projects
  • individual restart of projects
• 0.6.0 :
  • added War exporation
  • now works with projects created outside the workspace
  • all libraries located in "JDK_HOME/jre/lib" are now included at launch
• 0.5.0 : added Web projects, a few minor bugs corrected
• 0.4.0 : first version

9. To do

• Any suggestion?

10. Know limitations
There is no management of virtual hosting, all projects are included in the default host.

11. Recommanded plugins
For a complete web developpement free solution, you may have a look at these plugins :

• Aston wizards : a set of wizards containing Servlet wizard : http://renaud91.free.fr/Plugins/index_en.html
• Lomboz : J2EE developpement containing text based JSP and HTML editor : http://www.objectlearn.com/
• Solar Eclipse : http://sourceforge.net/projects/solareclipse/

12. Feedback
Please if you can, send me a little mail at : resinforeclipse@netcourrier.com in English or French to say what you think about this plugin.

13. Post Scriptum
Just a few words to say that I'm very impressed of the Eclipse Platform and I just want to congratulate them.
It's my first UI development, so be indulgent with my code, don't hesitate to contact me if you find bugs or bad practices.