osgish
                               ======

INTRODUCTION

 Osgish is command line shell for OSGi. It is based on the Readline
 Library, Jolokia as JMX backend and Aries JMX as the OSGi Management
 layer, with Perl being the glue.

 Highlights of osgish are:

 * Readline and history support based on GNU Readline/History as
   known from other shells like 'bash'. When GNU Readline is not
   available, a pure Perl Module is used instead.
 * Context sensitive argument completion, e.g. on bundle symbolic
   names.
 * Colored output (can be switched off)
 * Multi-Server support
 * Remote operation via HTTP(S)

 THIS IS A PREVIEW. Currently you can list, start and stop bundles
 only. If you have a use case you want to have covered, please don't
 hesistate to contact [email protected].

 Said this, osgish is already pretty useful.

HOW IT WORKS

 Osgish consist of mainly two parts: A Perl command line script
 (along with some Perl modules) which connects to an OSGi container
 via a special OSGi agent bundle. This bundle contains for exports
 JMX information through an OSGi HttpService as JSON data. The JMX
 MBeans used are those provided by the Aries
 (http://aries.apache.org) which is the implementation of the OSGi
 Alliance Enterprise Expert Group (EEG) specification, especially the
 "JMX Management Model Specification".

 Although this setup sounds a bit involved, installation is not much
 more than installing a CPAN package and a provided OSGi bundle (the
 same as for jmx4perl).

INSTALLATION

 The Perl part installs as any other module via Module::Build, which
 you need to have installed. Using

 perl Build.PL
 ./Build
 ./Build test
 ./Build install

 will install the modules. If you have Java and Maven (a Java build
 tool) installed, the agent bundle will be compiled and packaged as
 well when you use './Build dist'. However, this is not required as a
 prepackaged bundle is contained within the agent directory.

 Osgish depends on the Perl Module 'Term::ReadLine' (indirectly via
 Term::ShellUI), which can be used with various backend Readline
 implementations. The most powerful (and hence recommended)
 implementation is GNU Readline/History Library which will be used if
 installed. It is really worth to go the extra way to install GNU
 readline, even on OS X or Windows (which is not trivial). E.g. for
 OS X you can use the package 'p5-term-readline-gnu' from Mac Ports
 to install readline along with the needed module. For Debian, the
 easiest way is to install the package 'libterm-readline-gnu-perl'
 via apt. However, the default implementation Term::ReadLine::Perl
 fits nicely, too.

 The agent parts comes in two flavors: A minimal
 'osgish-core-<version>.jar' bundle and and all-in-one bundle
 'osgish-bundle-<version>.jar'. The all-in-one bundle is the proper
 choice, if no HTTP service is already installed since it has Apache
 Felix HTTP service embedded. However, the pure bundle is recommended
 for installations onservers, which either provide an HTTP service on
 their own or has an HTTP connector installed (e.g. Glassfish). This
 pure bundle has a dependency on an OSGi HttpService, which needs to
 be available. Some OSGi container (like Glassfish v3) already comes
 with a HttpService as an installation option, for others you need to
 install one manually. A good choice is the Pax Web
 (http://wiki.ops4j.org/display/paxweb/Pax+Web) HttpService. Select
 the pax-web-jetty-bundle when downloading, it contains a all you
 need.

 Also, for the pure bundle the following Aries bundles, needs to be
 installed so that JMX exposes the required information:

 org.apache.aries.jmx (>= 0.3.0)
 org.apache.aries.util (>= 0.3.0)

 These bundles can be obtained from the Aries website aries.apache.org

 Finally, the bundle needs the Jolokia agent
 jolokia-osgi-<version>.jar, too. You can obtain it from
 www.jolokia.org.

 The bundles needs to be installed manully. Refer to your OSGi
 framework how to install a bundle (e.g. by calling 'install' in a
 OSGi shell or providing the bundle name during startup).

 Considered you the HttpService is available at its default port
 8080, you can connect to it via

 osgish http://localhost:8080/jolokia

 (This assumes, that the HttpService has a root context '/' which is
 true for Pax Web. Glassfish v3's HttpService use a root context of
 '/osgi' which results in a connect URL of
 http://localhost:8080/osgi/jolokia)

SUPPORTED OSGI PLATFORMS

 The following OSGi platform has been confirmed to work so far
 with:

 * Felix 4
 * Equinox 3.5
 * Glassfish v3.1
 * Spring dm Server 2.0

 Since OSGi bundles are highly portable, it is expected that every
 OSGi server with an installed HttpService should work out of the
 box.  Please open a bug at
 http://rt.cpan.org/Public/Bug/Report.html?Queue=osgish if you
 encounter any problems.

PLATFORM NOTES

 * Glassfish

   The easiest way to install bundles with glassfish is to copy the
   bundles to $DOMAIN/autodeploy/bundles Autodeployment can be
   switched on/off from the admin console ("Domain" : "Applications
   Configuration" : "Auto Deploy").

   Please ensure, that the Glassfish OSGi HTTP-Service is running.

   Copy the following jars into the $DOMAIN/autodeploy/bundles
   directory:

   jolokia-osgi-1.0.2.jar           (www.jolokia.org)
   org.apache.aries.jmx-0.3.jar     (aries.apache.org)
   org.apache.aries.util-0.3.jar    (aries.apache.org)
   osgish-core-0.3.0.jar            (from this distribution)

   In order to connect to the server when it is running, use

   osgish http://localhost:8080/osgi/jolokia

RESOURCES

 * Osgish's source is hosted on github.com. You can clone the
   repository with git://github.com/rhuss/osgish.git as URL

 * Osgish is hosted on CPAN at http://search.cpan.org/~roland/osgish

LICENSE

 Copyright (C) 2009-2011 Roland Huss ([email protected])

 Osgish is free software: you can redistribute it and/or modify it
 under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 2 of the License, or
 (at your option) any later version.

 Osgish is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with osgish.  If not, see <http://www.gnu.org/licenses/>.

 A commercial license is available as well. You can either apply the
 GPL or obtain a commercial license for closed source
 development. Please contact [email protected] for further information.

PROFESSIONAL SERVICES

 Just in case you need professional support for this module (or OSGi,
 JMX or JEE in general), contact [email protected] for further
 information (or use the contact form at
 http://www.consol.com/contact/ )

BUGS

 Please report any bugs and/or feature requests at
 http://rt.cpan.org/Public/Bug/Report.html?Queue=osgish

AUTHOR

 [email protected]

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.