Menu
▾
▴
[Jboss-svn-commits] JBL Code SVN: r1918 - in trunk/labs/kosmos/xdocs/reference: . images
|
From: <jbo...@li...> - 2005-12-21 16:19:28
|
Author: aron.gombas
Date: 2005-12-21 11:19:19 -0500 (Wed, 21 Dec 2005)
New Revision: 1918
Modified:
trunk/labs/kosmos/xdocs/reference/images/kosmos_logo.png
trunk/labs/kosmos/xdocs/reference/reference-manual.xml
Log:
Manual fixed based on Neal's review
Modified: trunk/labs/kosmos/xdocs/reference/images/kosmos_logo.png
===================================================================
(Binary files differ)
Modified: trunk/labs/kosmos/xdocs/reference/reference-manual.xml
===================================================================
--- trunk/labs/kosmos/xdocs/reference/reference-manual.xml 2005-12-21 15:13:55 UTC (rev 1917)
+++ trunk/labs/kosmos/xdocs/reference/reference-manual.xml 2005-12-21 16:19:19 UTC (rev 1918)
@@ -36,7 +36,7 @@
<para>Working as developer and later lead engineer on various
Java and C++ projects in the recent years, I had to spend a
- serious amount of time with reguarly checking various sources of
+ serious amount of time reguarly checking various sources of
information: build reports, source code metrics, PMD and
CheckStyle reports, the source code itself, project pages of the
dependencies, industry news in online mags and such. In other
@@ -68,7 +68,8 @@
and had explained them my plans. They liked the idea, it was in
sync with certain things what they wanted to do themselves, so
they invited my project as one of the first projects hosted in
- their new-born JBoss Labs forge.</para>
+ their new-born <ulink url="http://labs.jboss.com">JBoss Labs</ulink>
+ forge.</para>
<para>
<figure>
@@ -81,9 +82,20 @@
<para>In the very beginning, the project ran under a different
temporary codename, but when incubating it to JBoss Labs, I had
to find out the final name. As the guys at JBoss were waiting for
- me, I had to come up with a fancy name in a couple of hours. Finally, I
+ me, I had to come up with a fancy name in a couple of hours. I
decided to use the word <emphasis>kosmos</emphasis>, because of
- several reasons (not explained here).</para>
+ several reasons:
+ <itemizedlist>
+ <listitem>is there anything more beautyful than our universe
+ itself?</listitem>
+ <listitem>"mikrokozmosz" is a wonderful musical piece
+ by Bela Bartok, one of the greatest Hungarian composers</listitem>
+ <listitem>gives the opportunity to play more with the notions
+ related, like "kosmonaut"</listitem>
+ <listitem>a name with the length of six characters perfectly fits
+ Java package names, jar filenames and such</listitem>
+ </itemizedlist>
+ </para>
</section>
@@ -93,7 +105,9 @@
<para>Huge thanks to my wife, Szilva, for not giving up the
struggle for such a long time, and Damon Sicore and everyone else
- at JBoss Labs for their support.</para>
+ at <ulink url="http://labs.jboss.com">JBoss Labs</ulink> for
+ their support. Special thanks to every Kosmos project
+ contributor (you know, guys, who you are).</para>
</section>
@@ -126,17 +140,17 @@
<title>Vision</title>
- <para>The first releases of Kosmos focus on integrating only a
+ <para>The first releases of Kosmos focuses on integrating a
small set of de-facto standard open source tools like Subversion
- or CruiseControl. These releases will also establish a stable base for
- future development, and they target reaching a production-ready
+ or CruiseControl. These releases will form the base for
+ future development and aspire to reach a production-ready
state as soon as possible.</para>
- <para>For the long run, by leaving the door open with an
- extensible architecture, we consider supporting anything
- demanded: both popular open source and commercial tools if they
- are accessible through some kind of public web-services, API or
- at least by page-scraping (in case of web interfaces).</para>
+ <para>In the long run, we have left the door open with an
+ extensible architecture. We will consider supporting anything
+ demanded. That includes both popular open source and commercial tools if they
+ are accessible through some kind of public web-service, API, or
+ at by page-scraping (in case of web interfaces).</para>
</section>
@@ -151,34 +165,34 @@
<listitem>
- <para>Lightweight architecture through POJOs.</para>
+ <para>Lightweight architecture implemented with POJOs.</para>
</listitem>
<listitem>
- <para>Several independent and simplistic components instead
- of a single monolithic monster.</para>
+ <para>Several independent and simplistic components rather than
+ single monolithic one.</para>
</listitem>
<listitem>
- <para>Easy and flexible deployment: no changes to make
- in the monitored resources.</para>
+ <para>Easy and flexible deployment, and so no changes in the
+ monitored resources.</para>
</listitem>
<listitem>
<para>Full transparency for the monitored resources and no
- extra burden on those.</para>
+ extra burden on them.</para>
</listitem>
<listitem>
- <para>Maximal vendor-indepence: no proprietary features of
+ <para>Maximum vendor-indepence: no proprietary features of
servlet containers, application servers, portlet containers
or WebDAV servers.</para>
@@ -194,7 +208,7 @@
<listitem>
<para>Visualization by using charts and graphics instead of
- plain textual information, whereever possible.</para>
+ plain textual information, wherever possible.</para>
</listitem>
@@ -215,7 +229,7 @@
<listitem>
- <para>Java 1.5 language compatibility (however using some
+ <para>Java 1.5 language compatibility (some
of the language features introduced in Java 1.5 are not
compatible with Hessian).</para>
@@ -223,7 +237,7 @@
<listitem>
- <para>Portlets that are JSR-168-compliant.</para>
+ <para>Portlets that are perfectly JSR-168-compliant.</para>
</listitem>
@@ -330,8 +344,8 @@
<title>Compatibility</title>
- <para>Please see the detailed compatibility matrix maintained
- on the project website.</para>
+ <para>Please see the detailed compatibility matrix on the project
+ website.</para>
</section>
@@ -347,25 +361,24 @@
<para>The <quote>remote server</quote> component acts like a
traditional back-end: it collects, analyzes, stores and caches
- all the information rendered later by the front-end.</para>
-
- <para>You might want to ask, why is it necessary to complicate the
- deployment with this additional component? Having a single layer
+ all the information. It then provides results for the front-end.
+ You might ask, "Is it necessary to complicate the
+ deployment with this additional component?" Having a single layer
(portlets only, that access the monitored resources directly), it
could be much simpler!</para>
<para>The primary reason is that certain operations performed by
- the system (for instance monitoring a remote Subversion
+ the system (like monitoring a remote Subversion
repository) can be <emphasis>very</emphasis> expensive:
- traversing the repository content can easily took for hours
+ traversing the repository content can easily take hours,
depending on many factors like the repository complexity, server
- performance or network bandwidth. By using a simple caching
+ performance, or network bandwidth. By using a simple caching
mechanism built into the server component, if several portlet
- instances are monitoring the same repo and they fire identical
- requests, only the very first will result in a new traversal. The
+ instances are monitoring the same repository and they fire identical
+ requests, only the very first will result in a new traversal! The
other requests will receive the cached result until the first
cache-miss (which can be caused also by a time-out, of course).
- Even this naive mechanism gives a huge performance boost and puts
+ This simple mechanism gives a huge performance boost and puts
less burden on the <quote>target box</quote>, the Subversion
server in this case.</para>
@@ -383,7 +396,7 @@
<listitem>
<para>Provides Hessian-based web services for the portlets
- (i.e. view tier).</para>
+ (view tier).</para>
</listitem>
@@ -411,10 +424,10 @@
<quote>traditional</quote> web-application techniques, because
flexible customization was a high-priority project goal.</para>
- <para>You can easily configure custom-tailored portal pages, that
- can contain any of the portlets in various layouts. Also, you can
- mix Kosmos portlets with other portlets coming from other projects
- and vendors, without any restriction. The deployment and configuration
+ <para>You can set up any portal page, which can contain any
+ number of the portlets in various layouts. Also, you can
+ mix Kosmos portlets with portlets coming from other projects
+ or vendors, without any restriction. The deployment and configuration
process is portlet container-dependent, thus it is out of the scope of this
document. Please refer to the technical documentation of your
particular container.</para>
@@ -422,7 +435,7 @@
<para>
Using the portlet user interfaces should be straight-forward.
- There is a couple of common features supported by all the
+ There are a set of common features supported by all the
portlets:
<itemizedlist>
@@ -462,9 +475,9 @@
<para>This portlet monitors the continuous integration build
processes managed by CruiseControl, a very well-known continuous
- build framework. Thus it helps you to track whether the builds of
- your projects didn't get broken, without checking email
- reports or web reports one-by-one.</para>
+ build framework. It helps you to track whether the builds of
+ your projects break, without checking email,
+ reports, or web reports.</para>
<para>
@@ -474,7 +487,7 @@
<listitem>
<para>It reports on the build labels, build results,
- timestamps and unit test results. Also, you can get detailed
+ timestamps, and unit test results. You can also get detailed
information about the unit tests.</para>
</listitem>
@@ -502,7 +515,7 @@
<title>JIRA Monitoring portlet</title>
<para>This portlet monitors projects hosted by JIRA, a popular issue tracking
- and project management application. It helps you by giving an
+ and project management application. It helps you by giving a
quick overview about the state of several projects in a single
place.</para>
@@ -597,8 +610,8 @@
<title>Subversion Monitoring portlet</title>
<para>This portlet monitors repositories managed by Subversion, one of the
- most widely used version control systems. This way it helps you
- to track the activity and complexity of several separate
+ most widely used version control systems. It helps you
+ track the activity and complexity of several separate
repositories very easily in a single portlet.</para>
<para>
@@ -645,7 +658,7 @@
<para>
- Here we just list a couple of additional ideas which can make
+ Here are a couple of additional ideas which can make
your life easier when configuring your particular Kosmos portal
instance:
<itemizedlist>
@@ -654,9 +667,7 @@
<para>Combining Kosmos portlets with other portlets is a
good practice to maximize the information effectively
- aggregated on your portal page.</para>
-
- <para>Other than the standard
+ aggregated on your portal page. Other than the standard
Kosmos portlets, you should consider using: Forums portlet,
RSS portlet, Blog portlet, Poll portlet, CMS portlet and
Wiki portlet. All these (provided you use them in the right
@@ -667,22 +678,12 @@
<listitem>
- <para>If CruiseControl runs on a remote machine (not the
- same machine like the container which hosts Kosmos
- container), you can map the remote CruiseControl log
- directory to the local filesystem and monitor it.</para>
-
- </listitem>
-
- <listitem>
-
- <para>All portlets support multiple monitored resources,
- group those as you wish.</para>
- <para>For example, you can have a
+ <para>All portlets support multiple monitored resources, and you can
+ group them as you wish. For example, you can have a
separate portlet for monitoring Spring, and another for
- monitoring ACEGI, but it might make sense to group those as
- related packages together to a single portlet, plus keep
- all the Struts-related packages in another portlet and
+ monitoring ACEGI. It might make sense to group those as
+ related packages together within a single portlet, and keep
+ all the Struts-related packages in another portlet, and
Tomcat-related packages in a third one.</para>
</listitem>
@@ -718,15 +719,14 @@
<listitem>
<para>We offer deployment scripts in form of Ant build
- scripts, which automatize the deployment process. If you
+ scripts, which automate the deployment process. If you
want to use these, you will need to install Ant.
The default target of each script is <literal>redeploy</literal>,
which deletes the old deployment (if there exists) and deploys a
- new clean one.</para>
- <para>Of course, you can still deploy manually if Ant is not available in
- your environment. Even in this case, it's a good idea to
- look through the deploy scripts and then to follow the
- step-by-step guide provided in the next sections.</para>
+ new clean one.
+ Of course, you can still deploy manually if Ant is not available in
+ your environment. In any case, it's a good idea to
+ look through the deploy scripts.</para>
</listitem>
@@ -778,8 +778,8 @@
<listitem>
<para><emphasis>minimalistic</emphasis>: a single container
- which can act both as servlet-container for Kosmos server
- and for the WebDAV server and as portlet-container for the
+ which can act both as servlet-container for Kosmos server,
+ the WebDAV server, and the portlet-container for the
portlets. As result, there will be three separate web
applications running in the same container. This is the
simplest way to deploy Kosmos and it can be an effective
@@ -794,7 +794,7 @@
network: for example you can use Apache Tomcat as
servlet-container and JBoss AS with JBoss Portal as
portlet-container. It means that your components will run
- in separate JVMs which can be useful from stability or
+ in separate JVMs which can be useful from a stability or
security viewpoint.</para>
</listitem>
@@ -802,19 +802,19 @@
<listitem>
<para><emphasis>distributed</emphasis>: containers on
- separate nodes, for example <emphasis>server A</emphasis>
+ separate nodes. <emphasis>Server A</emphasis>
can run one instance of JBoss AS to host the server
- component, <emphasis>server C</emphasis> can run another to
+ component, <emphasis>server B</emphasis> can run another to
host the WebDAV repository, while <emphasis>server
C</emphasis> can run a third one to host the portlet
container.</para>
- <para>Moreover, for advanced users it is possible to deploy
+ <para>For advanced users it is possible to deploy
each service of the server component to different nodes if
that's necessary! You can fine-tune the performance of
the system this way.</para>
- <para>And since all the information is exposed as standard
+ <para>Since all the information is exposed as standard
Hessian web-services, it is possible and perfectly legal to
develop other types of front-end for the system: web
applications, applets or desktop applications and
@@ -825,7 +825,9 @@
</itemizedlist>
<figure>
+
<title>Minimalistic deployment</title>
+
<graphic fileref="images/kosmos_deployment.png"/>
</figure>
@@ -915,7 +917,7 @@
<para>
-
+ Follow these steps:
<orderedlist>
<listitem>
@@ -935,7 +937,7 @@
<listitem>
<para>You can deploy the server component into the Apache Tomcat
- instance used by Gridsphere simply by running the server deploy script:
+ instance used by Gridsphere, by running the server deploy script:
<programlisting>ant -f deploy-server-tomcat.xml</programlisting>
Please don't forget to set the <literal>CATALINA_HOME</literal>
environment variable before.
@@ -959,7 +961,7 @@
(e.g. <literal>http://localhost:8080/gridsphere</literal>), and
login with the default account (<literal>root</literal>
and empty password). After this, there are couple of extra steps
- that you have to do using the Gridsphere admin portlets:
+ that you can do using the Gridsphere admin portlets:
<orderedlist>
<listitem>
@@ -999,7 +1001,7 @@
<para>
-
+ Follow these steps:
<orderedlist>
<listitem>
@@ -1027,7 +1029,7 @@
<listitem>
- <para>Install JBoss Portal as written in its manual. Check
+ <para>Install JBoss Portal as written in its manual. Test
if there are no error messages in the JBoss AS
logfile.</para>
@@ -1094,9 +1096,9 @@
<listitem>
<para>You can deploy the server component into the Apache Tomcat
- instance used by Liferay simply by running the server deploy script:
+ instance used by Liferay, by running the server deploy script:
<programlisting>ant -f deploy-server-tomcat.xml</programlisting>
- Please don't forget to set the <literal>CATALINA_HOME</literal>
+ Don't forget to set the <literal>CATALINA_HOME</literal>
environment variable before.
</para>
@@ -1105,6 +1107,14 @@
<listitem>
<para>
+ Hot-deploy the portlets by running the portlet deploy script:
+ <programlisting>ant -f deploy-portlet-liferay-portal.xml</programlisting>
+ Edit this file and make sure the properties are correct. If you have CATALINA_HOME
+ set, you shouldn't have to worry about the <programlisting>container.dir</programlisting>
+ property. Ensure <programlisting>container.lib</programlisting> and
+ <programlisting>liferay.home</programlisting> are correct.
+
+
Hot-deploy the portlets as written at <ulink url="http://www.liferay.com/web/guest/documentation/development/hot_deploy">http://www.liferay.com/web/guest/documentation/development/hot_deploy</ulink>.
The portlet distribution package of Kosmos contains a customized version of
<filename>portlet-deployer-3.5.0.xml</filename> which you might find convenient
@@ -1193,7 +1203,7 @@
<listitem>
<para>You can deploy the server component into the Apache Tomcat
- instance used by Pluto simply by running the server deploy script:
+ instance used by Pluto, by running the server deploy script:
<programlisting>ant -f deploy-server-tomcat.xml</programlisting>
Please don't forget to set the <literal>CATALINA_HOME</literal>
environment variable before.
@@ -1211,9 +1221,9 @@
your portlets, otherwise your new portal page won't appear in the
menu!</para>
- <para>If for some reason you decided to do an automated deployment
- instead of using the administrative portlet, deploy the portlet web application by running the portlet deploy script as:
- <programlisting>ant -f deploy-portlet-pluto.xml</programlisting>
+ <para>If you decided to do an automated deployment
+ instead of using the administrative portlet, run the portlet deploy script:
+ <programlisting>ant -f deploy-portlet-pluto.xml</programlisting>.
After this, you have to manually update the following Pluto configuration
files:
<simplelist>
@@ -1254,7 +1264,7 @@
cache store mechanism, all configuration was moved to the Spring
XML.) It's absolutely straightforward to modify it, but
please note that the configuration changes might require
- reloading the servlet to take effect!
+ reloading the servlet!
</para>
@@ -1358,8 +1368,8 @@
</itemizedlist>
- For better understanding, please take a look at the full sample
- configuration files shipped in the distributed package.
+ Please take a look at the sample configuration files shipped in
+ the distributed package.
</para>
</section>
@@ -1424,18 +1434,11 @@
<listitem>
- <para><literal>CcMonitoringPortlet</literal>: path
- of the directories where CruiseControl produces its
- logfiles related to the projects to monitor. For
- example: <literal>
- /cruisecontrol/logs/myproject1,/cruisecontrol/logs/myproject2</literal>.
- <warning>
- <para>
- This portlet is not configured properly in the default <filename>
- portlet.xml</filename> shipped in the package,
- because it requires local paths!
- </para>
- </warning>
+ <para><literal>CcMonitoringPortlet</literal>: URLs of
+ the webpages where CruiseControl publishers produce their
+ output including the logfiles related to the projects to
+ monitor. For example: <literal>
+ http://cruisecontrol.jboss.com/cc/buildresults/ejb3-4.0-testsuite,http://cruisecontrol.jboss.com/cc/buildresults/ejb3-head-testsuite</literal>.
</para>
</listitem>
@@ -1526,10 +1529,10 @@
<title>SourceForge Monitoring</title>
</portlet-info>
</portlet></programlisting>
- Had you any problems or question, first please study the
+ If you have any problems or questions, please study the
default
- <filename>portlet.xml</filename>, probably you will find
- the answer there.
+ <filename>portlet.xml</filename>
+ , and you will probably find the answer there.
</para>
</section>
@@ -1690,7 +1693,7 @@
callback-like classes <literal>XxxHandler</literal> to do the
actual work.</para>
- <para>From server to the portlets, the data is transferred simply
+ <para>From the server to the portlets, the data is transferred simply
by instantiating the DTO classes in the <literal>
hu.midori.kosmos.protocol</literal> package and sending them over
the wire using Hessian. All this is very simple and
@@ -1702,7 +1705,7 @@
<title>Portlets architecture</title>
- <para>The portlets are extremely simple: they just connect to the
+ <para>The portlets are extremely simple: they just connect the
appropriate service, download a collection of DTOs and render the
JSPs. That's it.</para>
|
