Author: afedosik Date: 2007-11-01 10:38:01 -0400 (Thu, 01 Nov 2007) New Revision: 4628 Added: trunk/as/docs/reference/en/images/projects/ trunk/as/docs/reference/en/images/projects/wizard1.jpg trunk/as/docs/reference/en/images/projects/wizard2.jpg trunk/as/docs/reference/en/images/serverRuntimes/ trunk/as/docs/reference/en/images/serverRuntimes/installedRuntimes.JPG trunk/as/docs/reference/en/images/serverRuntimes/new4.0Runtime.JPG trunk/as/docs/reference/en/images/serverRuntimes/newRuntime.JPG trunk/as/docs/reference/en/images/serverRuntimes/newServer.JPG trunk/as/docs/reference/en/images/serverRuntimes/newServer2.JPG trunk/as/docs/reference/en/modules/DeployingModules.xml trunk/as/docs/reference/en/modules/WebToolsprojects.xml Modified: trunk/as/docs/reference/en/master.xml trunk/as/docs/reference/en/modules/RuntimesAndServers.xml Log: http://jira.jboss.com/jira/browse/RHDS-270 "out of date" chapters added (they will be updated then). Added: trunk/as/docs/reference/en/images/projects/wizard1.jpg =================================================================== (Binary files differ) Property changes on: trunk/as/docs/reference/en/images/projects/wizard1.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/as/docs/reference/en/images/projects/wizard2.jpg =================================================================== (Binary files differ) Property changes on: trunk/as/docs/reference/en/images/projects/wizard2.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/as/docs/reference/en/images/serverRuntimes/installedRuntimes.JPG =================================================================== (Binary files differ) Property changes on: trunk/as/docs/reference/en/images/serverRuntimes/installedRuntimes.JPG ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/as/docs/reference/en/images/serverRuntimes/new4.0Runtime.JPG =================================================================== (Binary files differ) Property changes on: trunk/as/docs/reference/en/images/serverRuntimes/new4.0Runtime.JPG ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/as/docs/reference/en/images/serverRuntimes/newRuntime.JPG =================================================================== (Binary files differ) Property changes on: trunk/as/docs/reference/en/images/serverRuntimes/newRuntime.JPG ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/as/docs/reference/en/images/serverRuntimes/newServer.JPG =================================================================== (Binary files differ) Property changes on: trunk/as/docs/reference/en/images/serverRuntimes/newServer.JPG ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/as/docs/reference/en/images/serverRuntimes/newServer2.JPG =================================================================== (Binary files differ) Property changes on: trunk/as/docs/reference/en/images/serverRuntimes/newServer2.JPG ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: trunk/as/docs/reference/en/master.xml =================================================================== --- trunk/as/docs/reference/en/master.xml 2007-11-01 14:35:29 UTC (rev 4627) +++ trunk/as/docs/reference/en/master.xml 2007-11-01 14:38:01 UTC (rev 4628) @@ -4,8 +4,9 @@ [<!ENTITY RuntimesAndServers SYSTEM "modules/RuntimesAndServers.xml"> <!ENTITY JBossASPerspective SYSTEM "modules/JBossASPerspective.xml"> +<!ENTITY WebToolsprojects SYSTEM "modules/WebToolsprojects.xml"> +<!ENTITY DeployingModules SYSTEM "modules/DeployingModules.xml"> - ]> <book> @@ -25,5 +26,6 @@ <toc/> &RuntimesAndServers; &JBossASPerspective; - + &WebToolsprojects; + &DeployingModules; </book> Added: trunk/as/docs/reference/en/modules/DeployingModules.xml =================================================================== --- trunk/as/docs/reference/en/modules/DeployingModules.xml (rev 0) +++ trunk/as/docs/reference/en/modules/DeployingModules.xml 2007-11-01 14:38:01 UTC (rev 4628) @@ -0,0 +1,77 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<chapter id="deploy"> + <title>Deploying Modules (out of date!)</title> + + <para> + Deploying to a server is mostly painless. + There are several ways to do it provided by Webtools, + and some additional methods provided by RHDS. </para> + <section><title>WTP Projects</title> + <section><title>Run On Server</title> + <para> + The first WTP method is to right-click on a webtools project, + such as a dynamic web project, ejb project, or ear project. + and then selecting <emphasis>run on server...</emphasis>. + The resulting dialog allows you to select which supporting + server the project can be published to. </para> + <para> + For the JBoss AS Server Adapters, publishing using this method + will force a default, best-guess, packaging configuration + for your project. This best-guess does <emphasis>not</emphasis> + publish incrementally, but instead repackages your entire + project into a .war, .jar, or .ear as appropriate, and + then coppies that file into the proper deploy directory. + For quicker smarter deployment, you will need to create + archives using the <emphasis>Project Archives</emphasis> + view and customize packaging yourself.</para> + </section> + <section><title>Add / Remove Projects</title> + <para> + Another method is in either the Servers View, or the JBoss + Servers View, to right click on a server and select + the <emphasis>Add or Remove Projects</emphasis> menu item. + This will bring up a dialog allowing you to either publish + projects / modules to a server, or remove them from the server.</para> + + <para> + If the selected module is a webtools project, + it will be published as in the <emphasis>Run on Server</emphasis> + option, with a best-guess full package. If, however, the selected + element is an archive from the <emphasis>Project Archives View</emphasis>, + it will be published according to the rules of that module type, which + are explained below.</para> + </section> + <section><title>JBoss Servers View, Publish</title> + <para> + In the JBoss Server's View, in the bottom section, is a + category called <emphasis>Modules</emphasis> which should + display all currently-published modules on the server. + By right-clicking on the desired module and selecting + <emphasis>Publish</emphasis>, it will force a full + rebuild of the entire module. </para> + </section> + <section><title>Project Archives View</title> + <para>In the Project Archives View, you can + right-click on any declared archive and select the + <emphasis>Publish To Server</emphasis> element, as described in + the last chapter. </para> + <para> + The ONLY WAY to ensure an <emphasis>Incremental Build</emphasis>, + such as changes to one jsp, html, or .class file, is to + enable the builder for that project. This is done by either changing + the global preferences for the Archives View, or in enabling + project-specific preferences and ensuring the builder is on.</para> + </section> + <!-- + <figure id="viewMain"> <title>JBoss Servers View: Main Section</title> + <mediaobject> + <alt>JBoss Servers View Main Section</alt> + <imageobject> + <imagedata + fileref="..\..\..\..\reference\en\images\asPerspective\viewMain.jpg"/> + </imageobject> + </mediaobject> + </figure> + --> + </section> + </chapter> Modified: trunk/as/docs/reference/en/modules/RuntimesAndServers.xml =================================================================== --- trunk/as/docs/reference/en/modules/RuntimesAndServers.xml 2007-11-01 14:35:29 UTC (rev 4627) +++ trunk/as/docs/reference/en/modules/RuntimesAndServers.xml 2007-11-01 14:38:01 UTC (rev 4628) @@ -10,6 +10,198 @@ <keyword>JBoss</keyword> </keywordset> </chapterinfo> - <title>Runtimes and Servers in the JBoss AS plugin</title> + <title>Runtimes and Servers in the JBoss AS plugin (out of date!)</title> + + <para>The JBoss AS plugin makes use of Webtools. This includes + starting and stopping servers in run or debug mode. It also includes + targeting webtools projects, such as dynamic web projects, + to certain server runtimes in order to ensure that the proper jars + from a specific server are added to the project's classpath properly. + </para> + <para> + In order to get started creating, running, and debugging J2EE + applications, we must start with creating our runtime and + server instances. + </para> + + <section> + <title>Webtools Runtimes</title> + <section><title>What is a runtime used for?</title> + <para> + In RHDS, Server Runtimes have one main purpose: + to point to a server installation somewhere on disk. + In our case, this will be a JBoss installation, and it + can than be used for two primary purposes. + + First, + it provides classpath additions to webtools projects that require them. + Second, for JBoss server at least, it provides information necessary + for the starting and stopping of the server, such as which jars + to run and which configuration to use. + </para> + </section> + + <section><title>Installing a new Runtime</title> + <para> + You can install runtimes into eclipse from the Window -&gt; Preferences... + menu, and then selecting Server -&gt; Installed Runtimes from the categories available. + </para> + <figure id="installedRuntimeWindow"> <title>Installed Runtimes</title> + <mediaobject> + <alt>Installed Server Runtime Preferences</alt> + <imageobject> + <imagedata + fileref="..\..\..\..\reference\en\images\serverRuntimes\installedRuntimes.JPG"/> + </imageobject> + </mediaobject> + </figure> + + + <para> + From this preference page you can see what runtimes are declared, + and what type they are. In the image shown above, there are three declared + runtimes, including a Tomcat 5.5 instance and a JBoss 4.2 instance. + </para> + + <para> + To create a JBoss runtime, we begin by clicking the add button. + This will open another dialog that allows us to choose what type + of runtime we want to create. Most of the runtime options are provided + by webtools, but those provided by RHDS are the ones we will focus on. + + </para> + + <figure id="addRuntimeWindow"> <title>Adding a Runtime</title> + <mediaobject> + <alt>Adding a Runtime</alt> + <imageobject> + <imagedata + fileref="..\..\..\..\reference\en\images\serverRuntimes\newRuntime.JPG"/> + </imageobject> + </mediaobject> + </figure> + + <para> + As seen above, there appear to be two JBoss categories. The first is + contributed by webtools, and is a generic adapter that is not upkept very well. + For this reason, RHDS provides updated and supported adapters of our own. + There is one for each of JBoss 3.2, 4.0, amd 4.2. You'll also note a deploy-only + runtime type. This type provides no classpath for webtools projects. + It is used solely by it's server type for the purpose of setting up a deploy directory + for users who don't wish to make use of starting, stopping, or debugging their projects + inside eclipse. + </para> + + + <figure id="add40RuntimeWindow"> <title>Adding a JBoss 4.0 Runtime</title> + <mediaobject> + <alt>Adding a JBoss 4.0 Runtime</alt> + <imageobject> + <imagedata + fileref="..\..\..\..\reference\en\images\serverRuntimes\new4.0Runtime.JPG"/> + </imageobject> + </mediaobject> + </figure> + + <para> + As shown above, all you need to do to create the runtime is to name it, browse to it's install directory, + select a Java Runtime Environment, and select which configuration you want. + As you browse to a valid installation folder, the list of configurations will + update allowing you to select the configuration of your choice. + </para> + <para> + Once the runtime is created, the configuration is an unchanging property + of that runtime. This is because many of the jars + necessary to provide for classpaths, such as the ejb3 jar locations or the servlet jar locations, + are located in deploy directories of each configurations (depending on which + version of JBoss is being used). Because of this, to compile against + a different configuration's jars, you will need to create a new runtime from that configuration. + </para> + <para> + Also, because of the open-source nature of JBoss, it is likely that a user may want to + modify and repackage some of the configuration-specific jboss jars and create + their own configuration using those modified jars. Rather than forcing the user to copy his + entire JBoss installation, this structure allows them to create only a new configuration instead. + </para> + <para> + As a result of having each runtime represent a specific configuration rather than + the server installation as a whole, it is very likely you'll create several different runtimes + to test each of your configurations. It becomes important to ensure your runtimes, + and later your servers, are given descriptive names that help you remember which is which. + It will do no good to try to remember if "JBoss-runtime 5" is the 4.0 install with ejb3? Or the + 4.2 install's custom configuration you decided to create. + </para> + <para> + After pressing finish, you'll see that your new runtime has been added to the list + and can now be targeted by webtools type projects or servers, both of which we'll get to later. + </para> + </section> + </section> + + + + + <section> + <title>Webtools Servers</title> + <section> + <title>What is a Server used for?</title> + <para> + Webtools servers are eclipse-representations of a backing server installation. + They are used to start or stop servers, deploy to servers, or debug code + that will run on the server. They keep track of what modules (jars, wars, etc) + you deploy to the server and also allow you to undeploy those modules. </para> + <para> + Servers can be started or stopped with different command-line arguments. + They are often backed by a runtime object representing that server's location. </para> + </section> + <section> + <title>Creating a New Server</title> + <para> + There are many ways to get to the new server wizard. One way + is to use the old standard File -&gt; New -&gt; Other... wizard, + and type in Server. This should show the screen below, which + does not look that different from the initial screen when + creating a new runtime. </para> + <figure id="addServerWindow"> <title>Adding a JBoss Server</title> + <mediaobject> + <alt>Adding a JBoss Server</alt> + <imageobject> + <imagedata + fileref="..\..\..\..\reference\en\images\serverRuntimes\newServer.JPG"/> + </imageobject> + </mediaobject> + </figure> + <para> + Because the server object is what keeps track of things like command line arguments + when starting or stopping, and runtimes keep track of the location of the installation, + each server instance must be backed by an appropriate runtime. </para> + <para> + Because there may be many runtimes of each type declared, the wizard allows you to select + which runtime you want your server to be backed by. The combo box below the view lets you + select which declared runtime to use. For example, if there were already multiple JBoss 4.0 + runtimes declared, the combo box would list all of the 4.0 runtimes available. </para> + <para> + If none of the runtimes declared are one you want to use, for example if + you declared a default and a minimal runtime before but now want your server + to be backed by the ALL configuration, then you can click on the + <emphasis>Installed Runtimes... </emphasis> Button to bring up the preference page + shown at the beginning of this chapter. </para> + <para> + If the server you want to create doesn't have any installed runtime yet, the combo + box and button will disappear, and the next page in the wizard will force you to create + the associated runtime first. </para> + <para> + Either way, after targeting your server to a runtime, the final screen + in this wizard is largely confirmational, giving the user a chance to verify + that he's selected the appropriate runtime. It also allows the user + to name the server appropriately. </para> + </section> + </section> + + <section> + <title>Well then...</title> + <para>Now that we've created our runtimes and servers, + we'll explore how to use them in future chapters. </para> + </section> </chapter> Added: trunk/as/docs/reference/en/modules/WebToolsprojects.xml =================================================================== --- trunk/as/docs/reference/en/modules/WebToolsprojects.xml (rev 0) +++ trunk/as/docs/reference/en/modules/WebToolsprojects.xml 2007-11-01 14:38:01 UTC (rev 4628) @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<chapter id="webtoolsProjects"> + <title>Webtools Projects (out of date!)</title> + <section><title>Description</title> + <para> + Webtools provides what are called "faceted" projects, + Their most popular such projects are their J2EE projects, + such as their Dynamic Web Project, their EJB Project, + or their EAR project. </para> + <para> + The idea behind faceted projects is that each project + can accept units of functionality, or facets, which can be + added or removed by the user. Some examples of these facets + are adding a webdoclet facet to a web project, or an + ejbdoclet to an EJB Project. </para> + <para> + Most often, these "facets" either add to the project's classpath, + enable a builder, or watch the project in some other fashion. </para> + <para> + WTP projects have undergone some criticism as being + <emphasis>over-engineered</emphasis> or too restrictive in their + design. WTP projects are set up in a tree-relationship to each other, + where one project can be a child of another. For example, an EAR + project may have a Web Project child, an EJB project child, + or other types. </para> + <para> + The benefit of this is that the structure of your projects is + then known, and packaging it up *should* be trivial. However, + if your project is non-standard, or you feel too confined by + such rigid structural requirements, you can still choose to + package your project using the Archives plugin as described + in the last chapter</para> + + </section> + <section><title>Faceted Project Wizards</title> + <figure id="faceted1"> <title>Faceted Project Wizard: First Page</title> + <mediaobject> + <alt>Faceted Project Wizard: First Page</alt> + <imageobject> + <imagedata width="5in" scalefit="0" + fileref="..\..\..\..\reference\en\images\projects\wizard1.jpg"/> + </imageobject> + </mediaobject> + </figure> + <para> + The first page of most WTP projects allows you to target a specific runtime, + representing a server's library location. It will also provide you the ability to + add this project to an EAR project, and select a pre-selected default set of facets, + called a configuration, rather than manually select each facet you might want.</para> + <para> + Selecting the runtime, again, allows the project to install the proper + classpaths to the project so it knows what code to compile against.</para> + <figure id="faceted2"> <title>Faceted Project Wizard: Second Page</title> + <mediaobject> + <alt>Faceted Project Wizard: Second Page</alt> + <imageobject> + <imagedata width="5in" scalefit="0" + fileref="..\..\..\..\reference\en\images\projects\wizard2.jpg"/> + </imageobject> + </mediaobject> + </figure> + <para> + The second page of the wizard allows you to enable or disable specific facets, as + described above. Some facets may require others, and some may conflict with others, + but on the whole this page allows you to add any number of facets that don't conflict + with each other. </para> + <para> + Further pages are specific to either hte project type, or the facets selected.</para> + </section> +</chapter>