Author: ochikvina Date: 2008-01-16 13:28:06 -0500 (Wed, 16 Jan 2008) New Revision: 5750 Modified: trunk/as/docs/reference/en/modules/runtimes_servers.xml Log: http://jira.jboss.com/jira/browse/JBDS-199 - updating the chapter according to Max remarks Modified: trunk/as/docs/reference/en/modules/runtimes_servers.xml =================================================================== --- trunk/as/docs/reference/en/modules/runtimes_servers.xml 2008-01-16 18:18:10 UTC (rev 5749) +++ trunk/as/docs/reference/en/modules/runtimes_servers.xml 2008-01-16 18:28:06 UTC (rev 5750) @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="UTF-8"?> <chapter id="runtimes_servers" xreflabel="runtimes_servers"> - <?dbhtml filename="runtimes_servers.html"?> + <?dbhtml filename="runtimes_servers.html"?> <chapterinfo> <keywordset> <keyword>JBoss Developer Studio</keyword> @@ -10,32 +10,43 @@ <keyword>JBoss</keyword> </keywordset> </chapterinfo> - <title>Runtimes and Servers in the JBoss AS plugin</title> + <title>Runtimes and Servers in the JBoss AS plugin</title> - <para>In this chapter we will discuss how to install runtimes and servers</para> + <para>In this chapter we will discuss how to install runtimes and servers.</para> <!-- <para>First of all it's necessary to say a few words about WTP </para> --> <!-- The Eclipse Web Tools Platform (WTP) project extends the Eclipse platform with tools for developing Web and Java EE applications. It includes source and graphical editors for a variety of languages, wizards and built-in applications to simplify development, and tools and APIs to support deploying, running, and testing apps. --> - <para>The JBoss AS plugin makes use of WTP. This includes starting and stopping servers in run or debug mode. It also includes - targeting WTP 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 <property>runtime</property> and - <property>server</property> instances.</para> - + <para>The JBoss AS plugin makes use of WTP. This includes starting and stopping servers in run or + debug mode. It also includes targeting WTP 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 <property>runtime</property> and <property>server</property> instances.</para> + <section> <title>WTP Runtimes</title> - <para>In JBoss Tools, the main purpose of Server Runtimes is 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:</para> - <itemizedlist> - <listitem><para>it provides classpath additions to WTP projects that require them.</para></listitem> - <listitem><para>For JBoss server at least, it provides information necessary for the starting and stopping of the server, it tells which jars to run and which configuration to use.</para></listitem> - </itemizedlist> - - <section id="InstNewRuntime"><title>Installing a new Runtime</title> - <para>You can install runtimes into eclipse from the <emphasis><property>Window &gt; Preferences... </property></emphasis> - menu, and then select <emphasis><property>Server &gt; Installed Runtimes</property></emphasis> from the categories available.</para> + <para>In JBoss Tools, the main purpose of Server Runtimes is 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:</para> + <itemizedlist> + <listitem> + <para>it provides classpath additions to WTP projects that require them.</para> + </listitem> + <listitem> + <para>For JBoss server at least, it provides information necessary for the starting and + stopping of the server, it tells which jars to run and which configuration to use.</para> + </listitem> + </itemizedlist> + + <section id="InstNewRuntime"> + <title>Installing a new Runtime</title> + <para>You can install runtimes into eclipse from the <emphasis> + <property>Window &gt; Preferences... </property> + </emphasis> menu, and then select <emphasis> + <property>Server &gt; Installed Runtimes</property> + </emphasis> from the categories available.</para> <figure> <title>Installed Runtimes</title> <mediaobject> @@ -44,10 +55,19 @@ </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 two declared - runtimes, including a JBoss 4.2 instance.</para> - <para>To create a JBoss runtime, we begin by clicking the <emphasis><property>Add</property></emphasis> 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 WTP, but those provided by JBoss Tools are the ones we will focus on.</para> + <para>From this preference page you can see declared runtimes and their types as well. In the + image shown above, there are two declared runtimes, including a JBoss 4.2 instance.</para> + + <para>Here, it&apos;s possible to edit or remove existing runtimes as well as add a new + one.</para> + + <para>To create a JBoss runtime click <emphasis> + <property>Add</property> + </emphasis> button and choose necessary type of runtime from the appeared dialog. </para> + + <!--para>Most of the runtime options are provided by WTP, but those + provided by JBoss Tools are the ones we will focus on.</para--> + <figure> <title>Adding a Runtime</title> <mediaobject> @@ -56,10 +76,15 @@ </imageobject> </mediaobject> </figure> - <para>As seen above, there appear to be two JBoss categories. The first is contributed by WTP, and is a generic adapter that is not upkept very well. - For this reason, JBoss Tools provides updated and supported adapters of our own. There is one for each of JBoss 3.2, 4.0, and 4.2. You'll also note a deploy-only - runtime type. This type provides no classpath for WTP 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> + + <para>As seen above, there appear to be two JBoss categories. The first is contributed by WTP, + and is a generic adapter that is not upkept very well. For this reason, JBoss Tools provides + updated and supported adapters of our own. There is one for each of JBoss 3.2, 4.0, and 4.2. + You'll also note a deploy-only runtime type. This type provides no classpath for WTP + 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> <title>Adding a JBoss 4.2 Runtime</title> <mediaobject> @@ -68,61 +93,97 @@ </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 WTP type projects or servers, both of which we'll get to later.</para> + + <para>All you need here is to name chosen runtime (or you can leave offered name), browse to + its install directory and select a Java Runtime Environment. 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>The user is likely to want to modify some of the configuration-specific + jboss jars. In this case it's possible to create your own new 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>Press <emphasis> + <property>Finish</property> + </emphasis> to see your new runtime in the list.</para> </section> - + </section> - + <section> <title>WTP Servers</title> - <para>WTP 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 the 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> + <para>WTP 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 the 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> <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 <emphasis><property>File -&gt; New -&gt; Other... </property></emphasis>wizard, - and type in <emphasis><property>Server</property></emphasis>. This should show the screen below, which does not look that different from the initial screen when creating a new runtime. </para> - <figure> - <title>Adding a JBoss Server</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/runtimes_servers/runtimes_servers_4.png"/> - </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.2 runtimes declared, the combo box would list all of the 4.2 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><property>Installed Runtimes... </property></emphasis> button to bring up the preference page shown at the beginning of this chapter.</para> - <figure> - <title>Installed Server Runtime Environments</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/runtimes_servers/runtimes_servers_5.png"/> - </imageobject> - </mediaobject> - </figure> - <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> + <para>There are many ways to get to the new server wizard. One way is to use the old standard <emphasis> + <property>File &gt; New &gt; Other... </property> + </emphasis>wizard, and type in <emphasis> + <property>Server</property> + </emphasis>. This should show the screen below, which does not look that different from the + initial screen when creating a new runtime. </para> + <figure> + <title>Adding a JBoss Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtimes_servers/runtimes_servers_4.png"/> + </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.2 runtimes declared, the combo box would list all of the 4.2 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> + <property>Installed Runtimes... </property> + </emphasis> button to bring up the preference page shown at the beginning of this chapter.</para> + <figure> + <title>Installed Server Runtime Environments</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtimes_servers/runtimes_servers_5.png"/> + </imageobject> + </mediaobject> + </figure> + <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> - - </chapter> + +</chapter>