http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/instances.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/instances.adoc b/manual/src/main/asciidoc/users-guide/instances.adoc deleted file mode 100644 index 636245e..0000000 --- a/manual/src/main/asciidoc/users-guide/instances.adoc +++ /dev/null @@ -1,379 +0,0 @@ -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -= Instances - -A instance is a complete new Apache Karaf runtime, isolated from the other ones. - -The purpose is to easily create and manage a new Apache Karaf runtime without installing a complete distribution. - -A instance is a new instance that you can launch separately from the root one, and deploy applications into. It means that each instance is run on a different JVM. - -A instance does not contain a full copy of the Apache Karaf distribution, but only a set of the configuration files and data folder which contains all the runtime information, logs and temporary files. - -== Using the instance commands - -The *instance* commands allow you to create and manage instances. - -=== Creating instances - -You create a new runtime instance by typing [`instance:create`|/commands/instance-create] in the Karaf console. - -As shown in the following example, `instance:create` causes the runtime to create a new runtime installation in the active runtime's `instances/[name]} directory. The new instance is a new Karaf instance and is assigned an SSH port number based on an incremental count starting at 8101 and a RMI registry port number based on an incremental count starting at 1099. - ----- -karaf@root()> instance:create test ----- - -The new instance is fresh Apache Karaf instance. It uses default configuration files set, as you install a fresh Karaf distribution. - -You can enable the verbose mode for the `instance:create` command using the `-v` option: - ----- -karaf@root()> instance:create -v test -Creating new instance on SSH port 8103 and registry port 1101 / RMI server port 44446 at: /opt/karaf/instances/test -Creating dir: /opt/karaf/instances/test/bin -Creating dir: /opt/karaf/instances/test/etc -Creating dir: /opt/karaf/instances/test/system -Creating dir: /opt/karaf/instances/test/deploy -Creating dir: /opt/karaf/instances/test/data -Creating file: /opt/karaf/instances/test/etc/config.properties -Creating file: /opt/karaf/instances/test/etc/jre.properties -Creating file: /opt/karaf/instances/test/etc/custom.properties -Creating file: /opt/karaf/instances/test/etc/java.util.logging.properties -Creating file: /opt/karaf/instances/test/etc/org.apache.felix.fileinstall-deploy.cfg -Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.features.obr.cfg -Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.features.repos.cfg -Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.log.cfg -Creating file: /opt/karaf/instances/test/etc/org.ops4j.pax.logging.cfg -Creating file: /opt/karaf/instances/test/etc/org.ops4j.pax.url.mvn.cfg -Creating file: /opt/karaf/instances/test/etc/users.properties -Creating file: /opt/karaf/instances/test/etc/keys.properties -Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.features.cfg -Creating file: /opt/karaf/instances/test/etc/system.properties -Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.shell.cfg -Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.management.cfg -Creating file: /opt/karaf/instances/test/bin/karaf -Creating file: /opt/karaf/instances/test/bin/start -Creating file: /opt/karaf/instances/test/bin/stop ----- - -You can manually configure the different ports, the location of the instance, the Apache Karaf features URLs using different options of the `instance:create` command. -You can have details about these options using the `--help` option. - -=== Cloning an instance - -Instead of creating a fresh instance, you can clone an existing instance using `instance:clone`. - -The `instance:clone` command reuse the files from the source instance: - ----- -karaf@root()> instance:clone root test ----- - -You can have details about the cloning options using the `--help` option. - -=== Changing the instance location - -By default, the new instances storage is in the `KARAF_HOME/instance` directory. -You find a directory with the name of the instance storing the different instance files. - -You can change the location of the instance using the `-l` option to the `instance:create` and `instance:clone` commands: - ----- -karaf@root()> instance:create -v -l /tmp/test test -Creating new instance on SSH port 8102 and registry port 1100 / RMI server port 44445 at: /tmp/test -Creating dir: /tmp/test/bin -Creating dir: /tmp/test/etc -Creating dir: /tmp/test/system -Creating dir: /tmp/test/deploy -Creating dir: /tmp/test/data -Creating file: /tmp/test/etc/config.properties -Creating file: /tmp/test/etc/jre.properties -Creating file: /tmp/test/etc/custom.properties -Creating file: /tmp/test/etc/java.util.logging.properties -Creating file: /tmp/test/etc/org.apache.felix.fileinstall-deploy.cfg -Creating file: /tmp/test/etc/org.apache.karaf.features.obr.cfg -Creating file: /tmp/test/etc/org.apache.karaf.features.repos.cfg -Creating file: /tmp/test/etc/org.apache.karaf.log.cfg -Creating file: /tmp/test/etc/org.ops4j.pax.logging.cfg -Creating file: /tmp/test/etc/org.ops4j.pax.url.mvn.cfg -Creating file: /tmp/test/etc/users.properties -Creating file: /tmp/test/etc/keys.properties -Creating file: /tmp/test/etc/org.apache.karaf.features.cfg -Creating file: /tmp/test/etc/system.properties -Creating file: /tmp/test/etc/org.apache.karaf.shell.cfg -Creating file: /tmp/test/etc/org.apache.karaf.management.cfg -Creating file: /tmp/test/bin/karaf -Creating file: /tmp/test/bin/start -Creating file: /tmp/test/bin/stop ----- - -Careful, it's not possible to change the location of an instance once it has been created. - -NB: `instance:destroy` will remove the instance location for you. You don't have to remove the instance location "by hand". - -=== Changing instance ports - -You can change the SSH port number assigned to an instance using the `instance:ssh-port-change` command: - ----- -karaf@root()> instance:ssh-port-change test 8104 ----- - -where test is the instance name and 8104 is the new SSH port number to use for the test instance. - -You can change the RMI Registry port number (used by JMX) of an instance using the `instance:rmi-registry-port-change` command: - ----- -karaf@root()> instance:rmi-registry-port-change test 1102 ----- - -where test is the instance name and 1102 is the new RMI Registry port number to use for the test instance. - -You can also change the RMI Server port number (used by JMX too) of an instance using the `instance:rmi-server-port-change` command: - ----- -karaf@root()> instance:rmi-server-port-change test 44447 ----- - -where test is the instance name and 44447 is the new RMI Server port number to use for the test instance. - -NB: the instance has to be stopped to be able to change the port numbers. - -=== Starting instances - -New instances are created in a stopped state. - -To start an instance, you can use the `instance:start` command: - ----- -karaf@root()> instance:start test ----- - -where test is the instance name. - -=== Listing instances - -To list the instances and their current status, you can use the `instance:list` command: - ----- -karaf@root()> instance:list -SSH Port | RMI Registry | RMI Server | State | PID | Name -------------------------------------------------------------- - 8101 | 1099 | 44444 | Started | 19652 | root - 8104 | 1101 | 44446 | Stopped | 0 | test ----- - -An instance can be in the following status: - -- Stopped: the instance is stopped. -- Starting: the instance is starting. -- Started: the instance is up and running. You can connect and use it. - -=== Status of an instance - -You can get directly the status of a given instance using the `instance:status` command: - ----- -karaf@root()> instance:status test -Started ----- - -where test is the instance name. - -=== Connecting to an instance - -You can connect to a running instance directly from the root one using the `instance:connect` command: - ----- -karaf@root()> instance:connect test ----- - -where 'test' is the instance name where to connect to. - -By default, this command will use the same username used on the root instance, and the password will be prompted. - -You can use a different username using the `-u` or `--username` option. You can also provide the password using the -`-p` or `--password` option. - -If you don't provide any argument, you will logon on the instance: - ----- -karaf@test()> ----- - -Note the name of instance in the shell prompt (@test). - -You can logoff from the instance and return back to the root instance using the `logout` command or CTRL-D key binding: - ----- -karaf@test()> logout -karaf@root()> ----- - -The `instance:connect` command accepts shell commands as argument. It allows you to directly execute commands or scripts on the instance: - ----- -karaf@root()> instance:connect test feature:list -Name | Version | Installed | Repository | Description ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -standard | 3.0.0 | x | standard-3.0.0 | Karaf standard feature -aries-annotation | 3.0.0 | | standard-3.0.0 | Aries Annotations -wrapper | 3.0.0 | | standard-3.0.0 | Provide OS integration -service-wrapper | 3.0.0 | | standard-3.0.0 | Provide OS integration (alias to wrapper feature) -obr | 3.0.0 | | standard-3.0.0 | Provide OSGi Bundle Repository (OBR) support -config | 3.0.0 | x | standard-3.0.0 | Provide OSGi ConfigAdmin support -region | 3.0.0 | x | standard-3.0.0 | Provide Region Support -... ----- - -=== Stop an instance - -To stop an instance, you can connect to the instance (using `instance:connect`) and execute the `system:shutdown` -command. - -You can also use the [`instance:stop`|/commands/instance-stop] command: - ----- -karaf@root()> instance:stop test ----- - -where test is the instance name. - -The instance will go to the "Stopped" state. - -=== Destroy an instance - -You can completely delete a stopped instance using the `instance:destroy` command: ----- -karaf@root()> instance:destroy test ----- - -where test is the instance name. - -NB: the `instance:destroy` deletes the instance store (the location where the instance files are stored). - -=== Rename an instance - -You can change the name of a stopped instance using the `instance:rename` command: - ----- -karaf@root()> instance:rename test newTest ----- - -where test is the current instance name, and newTest the new instance name. - -== Instance script - -The `instance:*` commands require the root instance running. - -But, you can also administrate directly instances without the root instance, using the `bin/instance` Unix script -(or `bin/instance.bat` script on Windows). - -You find the same actions that you can do with the `instance:*` commands in the `instance[.bat]` script: - ----- -bin/instance -Available commands: - clone - Clones an existing container instance. - create - Creates a new container instance. - destroy - Destroys an existing container instance. - list - Lists all existing container instances. - opts-change - Changes the Java options of an existing container instance. - rename - Rename an existing container instance. - rmi-registry-port-change - Changes the RMI registry port (used by management layer) of an existing container instance. - rmi-server-port-change - Changes the RMI server port (used by management layer) of an existing instance. - ssh-port-change - Changes the secure shell port of an existing container instance. - start - Start an existing container instance. - status - Check the current status of an instance. - stop - Stop an existing container instance. -Type 'command --help' for more help on the specified command. ----- - -For instance, to list all the instances, you can use the `instance` script with the `list` command: - ----- -bin/instance list -SSH Port | RMI Registry | RMI Server | State | PID | Name ------------------------------------------------------------ - 8101 | 1099 | 44444 | Stopped | 0 | root - 8102 | 1100 | 44445 | Stopped | 0 | test ----- - -It's exactly the same as executing `instance:list` in the root instance. - -You can obtain details about commands options and arguments using the `--help` option. For instance: - ----- -bin/instance rename --help -DESCRIPTION - instance:rename - - Rename an existing container instance. - -SYNTAX - instance:rename [options] name new-name - -ARGUMENTS - name - The name of the container instance to rename - new-name - The new name of the container instance - -OPTIONS - --help - Display this help message - -v, --verbose - Display actions performed by the command (disabled by default) - ----- - -== JMX InstanceMBean - -On the JMX layer, you have a MBean dedicated to the management of the instances: the InstanceMBean. - -The ObjectName to use is `org.apache.karaf:type=instance,name=*`. - -=== Attributes - -The `Instances` attribute is a tabular data attribute providing details about the instances: - -* `Is Root` (boolean): if true, the instance is the root instance, false else. -* `JavaOpts` (string): it contains the JVM arguments used by the instance. -* `Location` (string): it's the path to the instance storage. -* `Name` (string): it's the name of the instance. -* `Pid` (long): it's the current system process ID (PID) of the instance process. -* `RMI Registry Port` (int): it's the port number of the instance RMI Registry (JMX). -* `RMI Server Port` (int): it's the port number of the instance RMI Server (JMX). -* `SSH Port` (int): it's the port number of the instance SSH Server. -* `State` (string): it's the current status of the instance (Stopped, Starting, Started). - -=== Operations - -The InstanceMBean provides the following operations, corresponding to the previous `instance:*` commands: -* `createInstance(instanceName, sshPort, rmiRegistryPort, rmiServerPort, location, javaOpts, features, featuresUrls)`: create a new instance. -* `changeSshPort(instanceName, port)`: change the SSH port of an instance. -* `changeRmiServerPort(instanceName, port)`: change the RMI server port of an instance. -* `changeRmiRegistry(instanceName, port)`: change the RMI registry port of an instance. -* `changeJavaOpts(instanceName, javaOpts)`: change the Java options of an instance. -* `destroyInstance(instanceName)`: destroy an instance. -* `startInstance(instanceName)`: start an instance. -* `startInstance(instanceName, options)`: start an instance with the given Java options. -* `startInstance(instanceName, options, wait, debug)`: start an instance with the given Java options. - If wait is true, this operation is waiting for the instance is in "Started" state. If debug is true, the instance is started in debug mode. -* `stopInstance(instanceName)`: stop an instance. -* `renameInstance(instanceName, newInstanceName)`: rename an instance. -* `renameInstance(instanceName, newInstanceName, verbose)`: rename an instance. If verbose is true, this operation provides details in the log. -* `cloneInstance(instanceName, cloneName, sshPort, rmiRegistryPort, rmiServerPort, location, javaOpts)`: clone an existing instance.
http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/jdbc.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/jdbc.adoc b/manual/src/main/asciidoc/users-guide/jdbc.adoc deleted file mode 100644 index bfac7e0..0000000 --- a/manual/src/main/asciidoc/users-guide/jdbc.adoc +++ /dev/null @@ -1,226 +0,0 @@ -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -= DataSources (JDBC) - -The Apache Karaf DataSources (JDBC) is an optional enterprise feature. - -You have to install the `jdbc` feature first: - ----- -karaf@root()> feature:install jdbc ----- - -This feature provides an OSGi service to create/delete JDBC datasources in the container and perform database operations (SQL queries). - -This JDBC OSGi service can be manipulated programmatically (see the developer guide for details), using the `jdbc:*` commands, or using the JDBC MBean. - -== Commands - -=== `jdbc:create` - -The `jdbc:create` command automatically creates a datasource definition file in the Apache Karaf `deploy` folder. - -The `jdbc:create` accepts a set of options and the name argument: - ----- -karaf@root()> jdbc:create --help -DESCRIPTION - jdbc:create - - Create a JDBC datasource - -SYNTAX - jdbc:create [options] name - -ARGUMENTS - name - The JDBC datasource name - -OPTIONS - -u, --username - The database username - -v, --version - The version of the driver to use - -t, --type - The JDBC datasource type (generic, MySQL, Oracle, Postgres, H2, HSQL, Derby, MSSQL) - -url - The JDBC URL to use - -p, --password - The database password - -i, --install-bundles - Try to install the bundles providing the JDBC driver - -d, --driver - The classname of the JDBC driver to use. NB: this option is used only the type generic - --help - Display this help message - ----- - -* the `name` argument is required. It's the name of the datasource. The name is used to identify the datasource, and to create the datasource definition file (`deploy/datasource-[name].xml`). -* the `-u` option is optional. It defines the database username. -* the `-v` option is optional. It "forces" a given JDBC driver version (only used with the `-i` option). -* the `-t` option is required. It defines the JDBC datasource type. Accepted values are: MySQL, Oracle, Postgres, Derby, H2, HSQL, MSSQL, Generic. Generic is a generic configuration file using DBCP to create a pooled datasource. When using generic, it's up to you to install the JDBC driver and configure the `deploy/datasource-[name].xml` datasource file. -* the `-url` option is optional. It defines the JDBC URL to access to the database. -* the `-p` option is optional. It defines the database password. -* the `-d` option is optional. It defines the JDBC driver classname to use (only used with the generic type). -* the `-i` option is optional. If specified, the command will try to automatically install the OSGi bundles providing the JDBC driver (depending of the datasource type specified by the `-t` option). - -For instance, to create an embedded Apache Derby database in Apache Karaf, you can do: - ----- -karaf@root()> jdbc:create -t derby -u test -i test ----- - -We can note that the Derby bundle has been installed automatically, and the datasource has been created: - ----- -karaf@root()> la -... -87 | Active | 80 | 10.8.2000002.1181258 | Apache Derby 10.8 -88 | Active | 80 | 0.0.0 | datasource-test.xml ----- - -We can see the `deploy/datasource-test.xml` datasource file. - -== `jdbc:delete` - -The `jdbc:delete` command deletes a datasource by removing the `deploy/datasource-[name].xml` datasource file: - ----- -karaf@root()> jdbc:delete test ----- - -{warning} -The `jdbc:delete` does not uninstall the JDBC driver bundles and does not remove the files created by the JDBC driver (or the database in case of embedded database). -It's up to you to remove it. -{warning} - -== `jdbc:datasources` - -The `jdbc:datasources` command lists the JDBC datasources: - ----- -karaf@root()> jdbc:datasources -Name | Product | Version | URL ------------------------------------------------------------------- -/jdbc/test | Apache Derby | 10.8.2.2 - (1181258) | jdbc:derby:test ----- - -== `jdbc:info` - -The `jdbc:info` command provides details about a JDBC datasource: - ----- -karaf@root()> jdbc:info /jdbc/test -Property | Value --------------------------------------------------- -driver.version | 10.8.2.2 - (1181258) -username | APP -db.version | 10.8.2.2 - (1181258) -db.product | Apache Derby -driver.name | Apache Derby Embedded JDBC Driver -url | jdbc:derby:test ----- - -== `jdbc:execute` - -The `jdbc:execute` command executes a SQL query that doesn't return any result on a given JDBC datasource. - -Typically, you can use the `jdbc:execute` command to create tables, insert values into tables, etc. - -For instance, we can create a `person` table on our `test` datasource: - ----- -karaf@root()> jdbc:execute /jdbc/test "create table person(name varchar(100), nick varchar(100))" ----- - -And we can insert some records in the `person` table: - ----- -karaf@root()> jdbc:execute /jdbc/test "insert into person(name, nick) values('foo','bar')" -karaf@root()> jdbc:execute /jdbc/test "insert into person(name, nick) values('test','test')" ----- - -== `jdbc:query` - -The `jdbc:query` command is similar to the `jdbc:execute` one but it displays the query result. - -For instance, to display the content of the `person` table, we can do: - ----- -karaf@root()> jdbc:query /jdbc/test "select * from person" -NICK | NAME --------------------------------- -bar | foo -test | test ----- - -== `jdbc:tables` - -The `jdbc:tables` command displays all tables available on a given JDBC datasource: - ----- -karaf@root()> jdbc:tables /jdbc/test -REF_GENERATION | TYPE_NAME | TABLE_NAME | TYPE_CAT | REMARKS | TYPE_SCHEM | TABLE_TYPE | TABLE_SCHEM | TABLE_CAT | SELF_REFERENCING_COL_NAME ----------------------------------------------------------------------------------------------------------------------------------------------------- - | | SYSALIASES | | | | SYSTEM TABLE | SYS | | - | | SYSCHECKS | | | | SYSTEM TABLE | SYS | | - | | SYSCOLPERMS | | | | SYSTEM TABLE | SYS | | - | | SYSCOLUMNS | | | | SYSTEM TABLE | SYS | | - | | SYSCONGLOMERATES | | | | SYSTEM TABLE | SYS | | - | | SYSCONSTRAINTS | | | | SYSTEM TABLE | SYS | | - | | SYSDEPENDS | | | | SYSTEM TABLE | SYS | | - | | SYSFILES | | | | SYSTEM TABLE | SYS | | - | | SYSFOREIGNKEYS | | | | SYSTEM TABLE | SYS | | - | | SYSKEYS | | | | SYSTEM TABLE | SYS | | - | | SYSPERMS | | | | SYSTEM TABLE | SYS | | - | | SYSROLES | | | | SYSTEM TABLE | SYS | | - | | SYSROUTINEPERMS | | | | SYSTEM TABLE | SYS | | - | | SYSSCHEMAS | | | | SYSTEM TABLE | SYS | | - | | SYSSEQUENCES | | | | SYSTEM TABLE | SYS | | - | | SYSSTATEMENTS | | | | SYSTEM TABLE | SYS | | - | | SYSSTATISTICS | | | | SYSTEM TABLE | SYS | | - | | SYSTABLEPERMS | | | | SYSTEM TABLE | SYS | | - | | SYSTABLES | | | | SYSTEM TABLE | SYS | | - | | SYSTRIGGERS | | | | SYSTEM TABLE | SYS | | - | | SYSVIEWS | | | | SYSTEM TABLE | SYS | | - | | SYSDUMMY1 | | | | SYSTEM TABLE | SYSIBM | | - | | PERSON | | | | TABLE | APP | | ----- - -== JMX JDBC MBean - -The JMX JDBC MBean provides the JDBC datasources, and the operations to manipulate datasources and database. - -The object name to use is `org.apache.karaf:type=jdbc,name=*`. - -=== Attributes - -The `Datasources` attribute provides a tabular data of all JDBC datasource, containing: - -* `name` is the JDBC datasource name -* `product` is the database product backend -* `url` is the JDBC URL used by the datasource -* `version` is the database version backend. - -=== Operations - -* `create(name, type, jdbcDriverClassName, version, url, user, password, installBundles)` creates a JDBC datasource (the arguments correspond to the options of the `jdbc:create` command). -* `delete(name)` deletes a JDBC datasource. -* `info(datasource)` returns a Map (String/String) of details about a JDBC `datasource`. -* `tables(datasource)` returns a tabular data containing the tables available on a JDBC `datasource`. -* `execute(datasource, command` executes a SQL command on the given JDBC `datasource`. -* `query(datasource, query` executes a SQL query on the given JDBC `datasource` and return the execution result as tabular data. - http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/jms.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/jms.adoc b/manual/src/main/asciidoc/users-guide/jms.adoc deleted file mode 100644 index 276980b..0000000 --- a/manual/src/main/asciidoc/users-guide/jms.adoc +++ /dev/null @@ -1,304 +0,0 @@ -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -= MOM (JMS) - -The Apache Karaf MOM (Messaging Oriented Middleware/JMS) is an optional enterprise feature. - -You have to install the `jms` feature first: - ----- -karaf@root()> feature:install jms ----- - -The `jms` feature doesn't install a JMS broker: it just installs the OSGi service, commands, and MBean to interact with -a JMS broker (not the broker itself). - -It means that you have to install a JMS broker itself. - -This JMS broker can be available: - -* outside of Apache Karaf, as a standalone broker. In that case, Apache Karaf JMS will remotely connect to the JMS broker. - For instance, you can use this topology with Apache ActiveMQ or IBM WebsphereMQ. -* embedded in Apache Karaf. With this topology, Apache Karaf itself provides a JMS broker service. Apache ActiveMQ provides - a native support in Apache Karaf. - -For instance, you can install Apache ActiveMQ directly in Apache Karaf: - ----- -karaf@root()> feature:repo-add activemq -Adding feature url mvn:org.apache.activemq/activemq-karaf/LATEST/xml/features -karaf@root()> feature:install activemq-broker ----- - -The `activemq-broker` feature installs: - -* a Apache ActiveMQ broker directly in Apache Karaf, bind to the `61616` port number by default. -* the Apache ActiveMQ WebConsole bound to `http://0.0.0.0:8181/activemqweb` by default. - -The Apache Karaf `jms` feature provides an OSGi service to create/delete JMS connection factories in the container -and perform JMS operations (send or consume messages, get information about a JMS broker, list the destinations, ...). - -This JMS OSGi service can be manipulated programmatically (see the developer guide for details), using the `jms:*` commands, or using the JMS MBean. - -== Commands - -=== `jms:create` - -The `jms:create` command creates a JMS connection factory in the Apache Karaf container. It automatically creates a -blueprint XML file in the `deploy` folder containing the JMS connection factory definition corresponding -to the type that you mentioned. - -The `jms:create` command accepts different arguments and options: - ----- -karaf@root()> jms:create --help -DESCRIPTION - jms:create - - Create a JMS connection factory. - -SYNTAX - jms:create [options] name - -ARGUMENTS - name - The JMS connection factory name - -OPTIONS - -u, --url - The JMS URL. NB: for WebsphereMQ type, the URL is hostname/port/queuemanager/channel - --help - Display this help message - -t, --type - The JMS connection factory type (ActiveMQ or WebsphereMQ) - ----- - -* the `name` argument is required. It's the name of the JMS connection factory. The name is used to identify the connection factory, and to create the connection factory definition file (`deploy/connectionfactory-[name].xml`). -* the `-t` (`--type`) option is required. It's the type of the JMS connection factory. Currently on `activemq` and `webspheremq` type are supported. If you want to use another type of JMS connection factory, you can create the `deploy/connectionfactory-[name].xml` file by hand (using one as template). -* the `-u` (`--url`) option is required. It's the URL used by the JMS connection factory to connect to the broker. If the type is `activemq`, the URL looks like `tcp://localhost:61616`. If the type is `webspheremq`, the URL looks like `host/port/queuemanager/channel`. - -For instance, to create a JMS connection factory for a Apache ActiveMQ broker, you can do: - ----- -karaf@root()> jms:create -t activemq -u tcp://localhost:61616 test ----- - -{warning} -The `jms:create` command doesn't install any feature or bundle providing the JMS connection factory classes (and dependencies). -You have to install the required features (for instance `activemq-broker` feature for Apache ActiveMQ), or bundles (for IBM WebsphereMQ) providing the JMS connection factory packages and classes. -{warning} - -In the previous example, we assume that you previously installed the `activemq-broker` feature. - -We can see the created JMS connection factory: - ----- -karaf@root()> la -... -151 | Active | 80 | 0.0.0 | connectionfactory-test.xml ----- - -The `connectionfactory-test.xml` file has been created in the `deploy` folder. - -By default, the `jms:create` command constructs a JNDI name for the connection factory: `/jms/[name]`. - -It means that the connection factory name to use for the other `jms:*` commands is `/jms/[name]`. - -=== `jms:delete` - -The `jms:delete` command deletes a JMS connection factory. The `name` argument is the name that you used at creation time: - ----- -karaf@root()> jms:delete test ----- - -=== `jms:connectionfactories` - -The `jms:connectionfactories` command lists the JMS connection factories: - ----- -karaf@root()> jms:connectionfactories -JMS Connection Factory ----------------------- -/jms/test ----- - -=== `jms:info` - -The `jms:info` command provides details about the JMS connection factory: - ----- -karaf@root()> jms:info /jms/test -Property | Value -------------------- -product | ActiveMQ -version | 5.9.0 ----- - -You can see the JMS broker product and version. - -If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options. - -=== `jms:queues` - -The `jms:queues` command lists the JMS queues available on a JMS broker. For instance: - ----- -karaf@root()> jms:queues /jms/test -JMS Queues ----------- -MyQueue ----- - -where `/jms/test` is the name of the JMS connection factory. - -If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options. - -{warning} -Depending of the JMS connection factory type, this command may not work. -For now, the command works only with Apache ActiveMQ. -{warning} - -=== `jms:topics` - -The `jms:topics` command lists the JMS topics available on a JMS broker. For instance: - ----- -karaf@root()> jms:topics /jms/test -JMS Topics ----------- -MyTopic ----- - -where `/jms/test` is the name of the JMS connection factory. - -If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options. - -{warning} -Depending of the JMS connection factory type, this command may not work. -For now, the command works only with Apache ActiveMQ. -{warning} - -=== `jms:send` - -The `jms:send` command sends a message to a given JMS queue. - -For instance, to send a message containing `Hello World` in the `MyQueue` queue, you can do: - ----- -karaf@root()> jms:send /jms/test MyQueue "Hello World" ----- - -If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options. - -=== `jms:consume` - -The `jms:consume` command consumes messages from a JMS queue. - -For instance, to consume all messages from `MyQueue`, you can do: - ----- -karaf@root()> jms:consume /jms/test MyQueue -2 message(s) consumed ----- - -If you want to consume only some messages, you can define a selector using the `-s` (`--selector`) option. - -If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options. - -{warning} -The `jms:consume` command just consumes (so removes) messages from a JMS queue. It doesn't display the messages. -If you want to see the details of messages, you can use the `jms:browse` command. -{warning} - -=== `jms:count` - -The `jms:count` command counts the number of pending messages into a JMS queue. - -For instance, if you want to know the number of messages on `MyQueue`, you can do: - ----- -karaf@root()> jms:count /jms/test MyQueue -Messages Count --------------- -8 ----- - -If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options. - -=== `jms:browse` - -The `jms:browse` command browses a JMS queue and display details about messages. - -For instance, to browse the `MyQueue` queue: - ----- -karaf@root()> jms:browse /jms/test MyQueue -Message ID | Content | Charset | Type | Correlation ID | Delivery Mode | Destination | Expiration | Priority | Redelivered | ReplyTo | Timestamp ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ -ID:vostro-59602-1387462183019-3:1:1:1:1 | Hello World | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:12 CET 2013 -ID:vostro-59602-1387462183019-3:2:1:1:1 | Hello ActiveMQ | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:16 CET 2013 -ID:vostro-59602-1387462183019-3:3:1:1:1 | Hello Karaf | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:19 CET 2013 ----- - -By default, the messages properties are not displayed. You can use the `-v` (`--verbose`) option to display the properties: - ----- -karaf@root()> jms:browse -v /jms/test MyQueue -Message ID | Content | Charset | Type | Correlation ID | Delivery Mode | Destination | Expiration | Priority | Redelivered | ReplyTo | Timestamp | Properties ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -ID:vostro-59602-1387462183019-3:1:1:1:1 | Hello World | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:12 CET 2013 | -ID:vostro-59602-1387462183019-3:2:1:1:1 | Hello ActiveMQ | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:16 CET 2013 | -ID:vostro-59602-1387462183019-3:3:1:1:1 | Hello Karaf | UTF-8 | | | Persistent | queue://MyQueue | Never | 4 | false | | Thu Dec 19 15:10:19 CET 2013 | ----- - -If you want to browse only some messages, you can define a selector using the `-s` (`--selector`) option. - -If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options. - -=== `jms:move` - -The `jms:move` command consumes all messages from a JMS queue and send it to another one. - -For instance, to move all messages from `MyQueue` queue to `AnotherQueue` queue, you can do: - ----- -karaf@root()> jms:move /jms/test MyQueue AnotherQueue -3 message(s) moved ----- - -== JMX JMS MBean - -The JMX JMS MBean provides the attributes and operations to manipulate the JMS connection factories and JMS messages. - -The object name to use is `org.apache.karaf:type=jms,name=*`. - -=== Attributes - -The `Connectionfactories` attribute provides the list of all JMS connection factories names. - -=== Operations - -* `create(name, type, url)` creates a JMS connection factory. -* `delete(name)` deletes a JMS connection factory. -* `Map<String, String> info(connectionFactory, username, password)` gets details about a JMS connection factory and broker. -* `int count(connectionFactory, queue, username, password)` counts the number of pending messages on a JMS queue. -* `List<String> queues(connectionFactory, username, password)` lists the JMS queues available on the JMS broker. -* `List<String> topics(connectionFactory, username, password)` lists the JMS topics available on the JMS broker. -* `TabularData browse(connectionFactory, queue, selector, username, password)` browses a JMS queue and provides a table of JMS messages. -* `send(connectionFactory, queue, content, replyTo, username, password)` sends a JMS message to a target queue. -* `int consume(connectionFactory, queue, selector, username, password)` consumes JMS messages from a JMS queue. -* `int move(connectionFactory, source, destination, selector, username, password)` moves messages from a JMS queue to another. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/jndi.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/jndi.adoc b/manual/src/main/asciidoc/users-guide/jndi.adoc deleted file mode 100644 index 2537dd2..0000000 --- a/manual/src/main/asciidoc/users-guide/jndi.adoc +++ /dev/null @@ -1,219 +0,0 @@ -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -= Naming (JNDI) - -The Apache Karaf Naming (JNDI) is an optional enterprise feature. - -You have to install the `jndi` feature first: - ----- -karaf@root()> feature:install jndi ----- - -Apache Karaf provides a complete JNDI support. - -You have two parts in the Apache Karaf JNDI support: - -* a fully compliant implementation of the OSGi Alliance JNDI Service specification. -* a more "regular" JNDI context, containing different names that you can administrate. - -== OSGi Services Registry and JNDI - -The OSGi Service Registry provides a centralized register/query capabilities for OSGi services. - -A common pattern outside of OSGi is to make use of JNDI API to access services from a directory system. -The OSGi service registry can be viewed as an example of such a system. - -Apache Karaf supports the `osgi:service` lookup scheme as defined by the JNDI Service Specification. - -The schema is: - ----- -osgi:service/<interface>[/<filter>] ----- - -For instance, you can directly use JNDI to get a OSGi service: - ----- -Context ctx = new InitialContext(); -Runnable r = (Runnable) ctx.lookup("osgi:service/java.lang.Runnable"); ----- - -== JNDI service - -Apache Karaf also supports regular JNDI, including a directoy system where you can register name bindings, sub-context, etc. - -It supports the standard JNDI API: - ----- -Context ctx = new InitialContext(); -Runnable r = (Runnable) ctx.lookup("this/is/the/name"); ----- - -It also allows you to bind some OSGi services as "pure" JNDI name. In that case, you don't have to use the specific -`osgi:service` scheme. - -== Commands - -Apache Karaf provides specific commands to manipulate the JNDI service. - -=== `jndi:names` - -The `jndi:names` command lists all JNDI names. It groups both the JNDI names from the `osgi:service` scheme and the -regular JNDI names: - ----- -karaf@root()> jndi:names -JNDI Name | Class Name ------------------------------------------------------------------- -osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl -jndi/service | org.apache.karaf.jndi.internal.JndiServiceImpl ----- - -We can see here the `osgi:service/jndi` name (using the `osgi:service` scheme) and `jndi/service` name (using the -regular JNDI service). - -The `jndi:names` command accepts an optional `context` argument to list names on the given context. - -For instance, you can list only names in the `jndi` sub-context: - ----- -karaf@root()> jndi:names jndi -JNDI Name | Class Name ----------------------------------------------------------- -service | org.apache.karaf.jndi.internal.JndiServiceImpl ----- - -{warning} -The `jndi:names` lists only names (the full qualified name). It means that the empty JNDI sub-contexts are not displayed. -To display all JNDI sub-contexts (empty or not), you can use the `jndi:contexts` command. -{warning} - -=== `jndi:contexts` - -The `jndi:contexts` command lists all JNDI sub-contexts: - ----- -karaf@root()> jndi:contexts -JNDI Sub-Context ----------------- -other/context -foo/bar ----- - -=== `jndi:create` - -The `jndi:create` command creates a new JNDI sub-context: - ----- -karaf@root()> jndi:create my/company ----- - -=== `jndi:delete` - -The `jndi:delete` command deletes a JNDI sub-context: - ----- -karaf@root()> jndi:delete my/company ----- - -=== `jndi:alias` - -The `jndi:alias` command creates a new JNDI name (alias) with an existing one. - -The existing JNDI name can be a regular one: - ----- -karaf@root()> jndi:alias bean/services/jndi aliases/services/jndi -karaf@root()> jndi:names -JNDI Name | Class Name ----------------------------------------------------------------------- -osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl -bean/services/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl -aliases/services/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl ----- - -or a name from the `osgi:service` schema: - ----- -karaf@root()> jndi:alias osgi:service/jndi alias/jndi/service -karaf@root()> jndi:names -JNDI Name | Class Name -------------------------------------------------------------------- -osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl -alias/jndi/service | org.apache.karaf.jndi.internal.JndiServiceImpl ----- - -NB: the `jndi:alias` automatically creates all required JNDI sub-contexts. - -=== `jndi:bind` - -The `jndi:bind` command binds an OSGi service with a JNDI name. - -The `jndi:bind` command requires an OSGi service ID and a JNDI name. The OSGi service ID can be found using the `service:list` command. - -For instance, we can bind the OSGi service with ID 344 with the JNDI name `services/kar`: - ----- -karaf@root()> jndi:bind 344 services/kar -karaf@root()> jndi:names -JNDI Name | Class Name -------------------------------------------------------------------------------- -osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl -services/kar | org.apache.karaf.kar.internal.KarServiceImpl ----- - -=== `jndi:unbind` - -The `jndi:unbind` command unbind a given JNDI name: - ----- -karaf@root()> jndi:names -JNDI Name | Class Name -------------------------------------------------------------------------------- -osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl -services/kar | org.apache.karaf.kar.internal.KarServiceImpl -karaf@root()> jndi:unbind services/kar -karaf@root()> jndi:names -JNDI Name | Class Name -------------------------------------------------------------------------------- -osgi:service/jndi | org.apache.karaf.jndi.internal.JndiServiceImpl ----- - -{warning} -It's not possible to unbind a name from the `osgi:service` schema, as it's linked to a OSGi service. -{warning} - -== JMX JndiMBean - -The JMX JndiMBean provides the JNDI names, and the operations to manipulate the JNDI service. - -The object name to use is `org.apache.karaf:type=jndi,name=*`. - -=== Attributes - -The `Names` attribute provides a map containing all JNDI names and class names from both `osgi:service` scheme -and the regular JNDI service. - -The `Contexts` attribute provides a list containing all JNDI sub-contexts. - -=== Operations - -* `getNames(context)` provides a map containing JNDI names and class names in a given JNDI sub-context. -* `create(context)` creates a new JNDI sub-context. -* `delete(context)` deletes a JNDI sub-context. -* `alias(name, alias` creates a JNDI name (alias) for a given one. -* `bind(serviceId, name` binds a JNDI name using an OSGi service (identified by its ID). -* `unbind(name)` unbinds a JNDI name. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/jpa.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/jpa.adoc b/manual/src/main/asciidoc/users-guide/jpa.adoc deleted file mode 100644 index 7edfa1d..0000000 --- a/manual/src/main/asciidoc/users-guide/jpa.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -= Persistence (JPA) - -Apache Karaf provides JPA persistence providers (such as Apache OpenJPA) to be easy to use (in a OSGi way) and provide -container managed persistence for applications (using Blueprint). - -Apache Karaf embeds Aries JPA, providing a very easy way to develop applications that use JPA persistence. - -See the developer guide for details about developing applications that use JPA. - -== Persistence engine features - -Apache Karaf provides a set of ready to use persistence engine features: - -* Apache OpenJPA. The `openjpa` feature installs the `jpa` feature with the Apache OpenJPA as persistence engine: - ----- -karaf@root()> feature:install openjpa ----- - -* Hibernate. The `hibernate` feature installs the `jpa` feature with the Hibernate persistence engine: - ----- -karaf@root()> feature:install hibernate ----- - -* EclipseLink. The `eclipselink` feature will be available in the next Apache Karaf release. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/jta.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/jta.adoc b/manual/src/main/asciidoc/users-guide/jta.adoc deleted file mode 100644 index 137b809..0000000 --- a/manual/src/main/asciidoc/users-guide/jta.adoc +++ /dev/null @@ -1,119 +0,0 @@ -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -= Transaction (JTA) - -Apache Karaf provides container managed transactions, available as OSGi services. - -As most of the enterprise features, it's an optional feature that you can install with: - ----- -karaf@root()> feature:install transaction ----- - -However, the `transaction` feature is installed (as a transitive dependency) when installing enterprise features -(like `jdbc` or `jms` features for instance). - -== Apache Aries Transaction and ObjectWeb HOWL - -The `transaction` feature uses Apache Aries and ObjectWeb HOWL. Aapache Aries Transaction "exposes" the transaction -manager as OSGi service. The actual implementation of the transaction manager is ObjectWeb HOWL. - -ObjectWeb HOWL is a logger implementation providing features required by the ObjectWeb JOTM project, with a public API -that is generally usable by any Transaction Manager. -ObjectWeb HOWL uses unformatted binary logs to maximize performance and specifies a journalization API with methods -necessary to support JOTM recovery operations. - -ObjectWeb HOWL is intended to be used for logging of temporary data such as XA transaction events. -It is not a replacement for traditional log kits such as LOG4J and Java SE Logging. - -In Apache Karaf, ObjectWeb HOWL (High-speed ObjectWeb Logger) is used to implement TransactionLog (in Aries Transaction), -providing a very performant transaction manager in an OSGi way. - -== Configuration - -The installation of the `transaction` feature installs a new configuration: `org.apache.aries.transaction`. - -You can see the configuration properties using: - ----- -karaf@root()> config:list "(service.pid=org.apache.aries.transaction)" ----------------------------------------------------------------- -Pid: org.apache.aries.transaction -BundleLocation: mvn:org.apache.aries.transaction/org.apache.aries.transaction.manager/1.1.0 -Properties: - aries.transaction.recoverable = true - aries.transaction.timeout = 600 - service.pid = org.apache.aries.transaction - org.apache.karaf.features.configKey = org.apache.aries.transaction - aries.transaction.howl.maxBlocksPerFile = 512 - aries.transaction.howl.maxLogFiles = 2 - aries.transaction.howl.logFileDir = /opt/apache-karaf-3.0.0/data/txlog - aries.transaction.howl.bufferSizeKBytes = 4 ----- - -* `aries.transaction.recoverable` property is a flag to enable support of recoverable resource or not. A recoverable - resource is a transactional object whose state is saved to stable storage if the transaction is committed, and whose - state can be reset to what it was at the beginning of the transaction if the transaction is rolled back. - At commit time, the transaction manager uses the two-phase XA protocol when communicating with the recoverable resource - to ensure transactional integrity when more than one recoverable resource is involved in the transaction being committed. - Transactional databases and message brokers like Apache ActiveMQ are examples of recoverable resources. - A recoverable resource is represented using the javax.transaction.xa.XAResource interface in JTA. - Default is `true`. -* `aries.transaction.timeout` property is the transaction timeout. If a transaction has a lifetime longer than this timeout - a transaction exception is raised and the transaction is rollbacked. Default is `600` (10 minutes). -* `aries.transaction.howl.logFileDir` property is the directory where the transaction logs (journal) are stored. - Default is `KARAF_DATA/txlog`. -* `aries.transaction.howl.maxLogFiles` property is the maximum number of transaction log files to retain. Combined with the - `aries.transaction.howl.maxBlocksPerFile`, it defines the transaction retention. - -You can change the configuration directly using the `config:*` commands, or the Config MBean. - -For instance, to increase the transaction timeout, you can do: - ----- -karaf@root()> config:edit org.apache.aries.transaction -karaf@root()> config:property-set aries.transaction.timeout 1200 -karaf@root()> config:update -karaf@root()> config:list "(service.pid=org.apache.aries.transaction)" ----------------------------------------------------------------- -Pid: org.apache.aries.transaction -BundleLocation: mvn:org.apache.aries.transaction/org.apache.aries.transaction.manager/1.1.0 -Properties: - aries.transaction.recoverable = true - aries.transaction.timeout = 1200 - service.pid = org.apache.aries.transaction - org.apache.karaf.features.configKey = org.apache.aries.transaction - aries.transaction.howl.maxBlocksPerFile = 512 - aries.transaction.howl.maxLogFiles = 2 - aries.transaction.howl.logFileDir = /opt/apache-karaf-3.0.0/data/txlog - aries.transaction.howl.bufferSizeKBytes = 4 ----- - -{warning} -The `transaction` feature defines the configuration in memory by default. It means that changes that you can do will -be lost in case of Apache Karaf restart. -If you want to define your own transaction configuration at startup, you have to create a `etc/org.apache.aries.transaction.cfg` -configuration file and set the properties and values in the file. For instance: - ----- -# etc/org.apache.aries.transaction.cfg -aries.transaction.recoverable = true -aries.transaction.timeout = 1200 -aries.transaction.howl.maxBlocksPerFile = 512 -aries.transaction.howl.maxLogFiles = 2 -aries.transaction.howl.logFileDir = /opt/apache-karaf-3.0.0/data/txlog -aries.transaction.howl.bufferSizeKBytes = 4 ----- -{warning} http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/users-guide/kar.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/users-guide/kar.adoc b/manual/src/main/asciidoc/users-guide/kar.adoc deleted file mode 100644 index a56cfe0..0000000 --- a/manual/src/main/asciidoc/users-guide/kar.adoc +++ /dev/null @@ -1,304 +0,0 @@ -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -= KAR - -As described in the [Provisioning section|provisioning], Apache Karaf features describe applications. - -A feature defines different resources to resolve using URL (for instance, bundles URLs, or configuration files URLs). -As described in the [Artifacts repositories and URLs section|urls], Apache Karaf looks for artifacts (bundles, -configuration files, ...) in the artifact repositories. -Apache Karaf may require to download artifacts from remote repositories. - -Apache Karaf provides a special type of artifact that package a features XML and all resources described in the features -of this XML. This artifact is named a KAR (KAraf aRchive). - -A KAR file is a zip archive containing the - -Basically, the kar format is a jar (so a zip file) which contains a set of feature descriptor and bundle jar files. - -A KAR file contains a `repository` folder containing: - -* a set of features XML files -* the artifacts following the Maven directory structure (`groupId/artifactId/version/artifactId-version.type`). - -For instance, the `spring-3.0.0.kar` contains: - ----- -~$ unzip -l spring-3.0.0.kar -Archive: spring-3.0.0.kar - Length Date Time Name ---------- ---------- ----- ---- - 143 2013-12-06 10:52 META-INF/MANIFEST.MF - 12186 2013-12-06 10:52 repository/org/apache/karaf/features/spring/3.0.0/spring-3.0.0-features.xml - 575389 2013-12-06 10:52 repository/commons-collections/commons-collections/3.2.1/commons-collections-3.2.1.jar - 232019 2013-12-06 10:52 repository/commons-beanutils/commons-beanutils/1.8.3/commons-beanutils-1.8.3.jar - 673109 2013-12-06 10:52 repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.struts/1.3.10_1/org.apache.servicemix.bundles.struts-1.3.10_1.jar - 37084 2013-12-06 10:52 repository/org/springframework/org.springframework.web.struts/3.2.4.RELEASE/org.springframework.web.struts-3.2.4.RELEASE.jar - 7411 2013-12-06 10:52 repository/org/springframework/org.springframework.instrument/3.2.4.RELEASE/org.springframework.instrument-3.2.4.RELEASE.jar - 246881 2013-12-06 10:52 repository/org/springframework/org.springframework.transaction/3.2.4.RELEASE/org.springframework.transaction-3.2.4.RELEASE.jar - 16513 2013-12-06 10:52 repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.aopalliance/1.0_6/org.apache.servicemix.bundles.aopalliance-1.0_6.jar - 881124 2013-12-06 10:52 repository/org/springframework/org.springframework.core/3.2.4.RELEASE/org.springframework.core-3.2.4.RELEASE.jar - 199240 2013-12-06 10:52 repository/org/springframework/org.springframework.expression/3.2.4.RELEASE/org.springframework.expression-3.2.4.RELEASE.jar - 614646 2013-12-06 10:52 repository/org/springframework/org.springframework.beans/3.2.4.RELEASE/org.springframework.beans-3.2.4.RELEASE.jar - 340841 2013-12-06 10:52 repository/org/springframework/org.springframework.aop/3.2.4.RELEASE/org.springframework.aop-3.2.4.RELEASE.jar - 877369 2013-12-06 10:52 repository/org/springframework/org.springframework.context/3.2.4.RELEASE/org.springframework.context-3.2.4.RELEASE.jar - 130224 2013-12-06 10:52 repository/org/springframework/org.springframework.context.support/3.2.4.RELEASE/org.springframework.context.support-3.2.4.RELEASE.jar - 30640 2013-12-06 10:52 repository/org/apache/karaf/deployer/org.apache.karaf.deployer.spring/3.0.0/org.apache.karaf.deployer.spring-3.0.0.jar - 51951 2013-12-06 10:52 repository/org/springframework/org.springframework.aspects/3.2.4.RELEASE/org.springframework.aspects-3.2.4.RELEASE.jar - 411175 2013-12-06 10:52 repository/org/springframework/org.springframework.jdbc/3.2.4.RELEASE/org.springframework.jdbc-3.2.4.RELEASE.jar - 48049 2013-12-06 10:52 repository/javax/portlet/portlet-api/2.0/portlet-api-2.0.jar - 190883 2013-12-06 10:52 repository/org/springframework/org.springframework.web.portlet/3.2.4.RELEASE/org.springframework.web.portlet-3.2.4.RELEASE.jar - 635680 2013-12-06 10:52 repository/org/springframework/org.springframework.web/3.2.4.RELEASE/org.springframework.web-3.2.4.RELEASE.jar - 645946 2013-12-06 10:52 repository/org/springframework/org.springframework.web.servlet/3.2.4.RELEASE/org.springframework.web.servlet-3.2.4.RELEASE.jar - 464911 2013-12-06 10:52 repository/org/springframework/org.springframework.test/3.2.4.RELEASE/org.springframework.test-3.2.4.RELEASE.jar - 69784 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-web/1.2.1/spring-osgi-web-1.2.1.jar - 16030 2013-12-06 10:52 repository/org/apache/geronimo/specs/geronimo-jta_1.1_spec/1.1.1/geronimo-jta_1.1_spec-1.1.1.jar - 32359 2013-12-06 10:52 repository/org/apache/geronimo/specs/geronimo-jms_1.1_spec/1.1.1/geronimo-jms_1.1_spec-1.1.1.jar - 208684 2013-12-06 10:52 repository/org/springframework/org.springframework.jms/3.2.4.RELEASE/org.springframework.jms-3.2.4.RELEASE.jar - 75672 2013-12-06 10:52 repository/org/springframework/org.springframework.oxm/3.2.4.RELEASE/org.springframework.oxm-3.2.4.RELEASE.jar - 393607 2013-12-06 10:52 repository/org/springframework/org.springframework.orm/3.2.4.RELEASE/org.springframework.orm-3.2.4.RELEASE.jar - 338559 2013-12-06 10:52 repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.cglib/3.0_1/org.apache.servicemix.bundles.cglib-3.0_1.jar - 35859 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-io/1.2.1/spring-osgi-io-1.2.1.jar - 362889 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-core/1.2.1/spring-osgi-core-1.2.1.jar - 120822 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-extender/1.2.1/spring-osgi-extender-1.2.1.jar - 24231 2013-12-06 10:52 repository/org/springframework/osgi/spring-osgi-annotation/1.2.1/spring-osgi-annotation-1.2.1.jar - 12597 2013-12-06 10:52 repository/org/apache/karaf/bundle/org.apache.karaf.bundle.springstate/3.0.0/org.apache.karaf.bundle.springstate-3.0.0.jar - 31903 2013-12-06 10:52 repository/org/eclipse/gemini/blueprint/gemini-blueprint-io/1.0.0.RELEASE/gemini-blueprint-io-1.0.0.RELEASE.jar - 578205 2013-12-06 10:52 repository/org/eclipse/gemini/blueprint/gemini-blueprint-core/1.0.0.RELEASE/gemini-blueprint-core-1.0.0.RELEASE.jar - 178525 2013-12-06 10:52 repository/org/eclipse/gemini/blueprint/gemini-blueprint-extender/1.0.0.RELEASE/gemini-blueprint-extender-1.0.0.RELEASE.jar ---------- ------- - 9803140 38 files ----- - -As a KAR file is a simple zip file, you can create the KAR file by hand. - -For instance, the following Unix commands create a very simple KAR file: - ----- -~$ mkdir repository -~$ cp /path/to/features.xml repository/features.xml -~$ cp /path/to/my.jar repository/my/project/my/1.0.0/my-1.0.0.jar -~$ zip -r my.kar repository -updating: repository/ (stored 0%) - adding: repository/my/project/my/1.0.0/my-1.0.0.jar (deflated 0%) ----- - -You can create KAR files using Apache Maven, or directly in the Apache Karaf console. - -== Maven - -Apache Karaf provides a Maven plugin: `karaf-maven-plugin`. - -The Apache Karaf Maven plugin provides the `kar` goal. - -The `kar` goal does: -1. Reads all features specified in the features XML. -2. For each feature described in the features XML, the goal resolves the bundles described in the feature. -3. The goal finally packages the features XML, and the resolved bundles in a zip file. - -For instance, the following Maven POM create `my-kar.kar` - -For instance, you can use the following POM to create a kar: - -{code:lang=xml} -<?xml version="1.0" encoding="UTF-8"?> -<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - - <modelVersion>4.0.0</modelVersion> - - <groupId>my.groupId</groupId> - <artifactId>my-kar</artifactId> - <version>1.0</version> - <packaging>pom</packaging> - - <build> - <plugins> - <plugin> - <groupId>org.apache.karaf.tooling</groupId> - <artifactId>karaf-maven-plugin</artifactId> - <version>3.0.0</version> - <executions> - <execution> - <id>kar</id> - <goals> - <goal>kar</goal> - </goals> - <configuration> - <featuresFile>src/main/resources/features.xml</featuresFile> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> - -</project> ----- - -To create the KAR file, simply type: - ----- -~$ mvn install ----- - -Uou will have your kar in the `target` directory. - -== Commands - -Apache Karaf provides `kar:*` commands to manage KAR archives. - -=== `kar:list` - -The `kar:list` command lists the installed KAR archives. - ----- -karaf@root()> kar:list -KAR Name -------------------- -my-kar-1.0-SNAPSHOT ----- - -A KAR is identified by its name. - -=== `kar:create` - -Instead of using the `karaf-maven-plugin` or create the KAR archive by hand, you can use the `kar:create` command. - -The `kar:create` command creates a KAR file using a registered features repository. - -For instance, you want to create a KAR file for the Pax Web repository. - -The `feature:repo-list` command gives you the list of registered features repositories: - ----- -karaf@root()> feature:repo-list -Repository | URL -------------------------------------------------------------------------------------------------------- -standard-3.0.0 | mvn:org.apache.karaf.features/standard/3.0.0/xml/features -enterprise-3.0.0 | mvn:org.apache.karaf.features/enterprise/3.0.0/xml/features -spring-3.0.0 | mvn:org.apache.karaf.features/spring/3.0.0/xml/features -org.ops4j.pax.web-3.0.5 | mvn:org.ops4j.pax.web/pax-web-features/3.0.5/xml/features ----- - -You can use one of these features repositories to create the kar file: - ----- -karaf@root()> kar:create org.ops4j.pax.web-3.0.5 -Adding feature pax-war -Adding feature pax-http-whiteboard -Adding feature pax-jetty -Adding feature pax-tomcat -Adding feature pax-http -Kar file created : /opt/apache-karaf-3.0.0/data/kar/org.ops4j.pax.web-3.0.5.kar ----- - -You can see that the KAR file has been created in the `KARAF_DATA/kar` folder. - -By default, the `kar:create` command creates a KAR file, packaging all features in the features descriptor. - -You can provide the list of features that you want to package into the KAR file: - ----- -karaf@root()> kar:create org.ops4j.pax.web-3.0.5 pax-jetty pax-tomcat -Adding feature pax-jetty -Adding feature pax-tomcat -Kar file created : /opt/apache-karaf-3.0.0/data/kar/org.ops4j.pax.web-3.0.5.kar ----- - -=== `kar:install` - -You can deploy a KAR file using `kar:install` command. - -The `kar:install` command expects the KAR URL. Any URL described in the [Artifacts repositories and URLs section|urls] -is supported by the `kar:install` command: - ----- -karaf@root()> kar:install file:/tmp/my-kar-1.0-SNAPSHOT.kar ----- - -The KAR file is uncompressed and populated the `KARAF_BASE/system` folder. - -The Apache Karaf KAR service is looking for features XML files in the KAR file, registers the features XML and automatically -installs all features described in the features repositories present in the KAR file. - -=== `kar:uninstall` - -The `kar:uninstall` command uninstall a KAR file (identified by a name). - -By uninstall, it means that: - -* the features previously installed by the KAR file are uninstalled -* delete (from the `KARAF_DATA/system` repository) all files previously "populated" by the KAR file - -For instance, to uninstall the previously installed `my-kar-1.0-SNAPSHOT.kar` KAR file: - ----- -karaf@root()> kar:uninstall my-kar-1.0-SNAPSHOT ----- - -== Deployer - -Apache Karaf also provides a KAR deployer. It means that you can drop a KAR file directly in the `deploy` folder. - -Apache Karaf will automatically install KAR files from the `deploy` folder. - -You can change the behaviours of the KAR deployer in the `etc/org.apache.karaf.kar.cfg`: - ----- -################################################################################ -# -# Licensed to the Apache Software Foundation (ASF) under one or more -# contributor license agreements. See the NOTICE file distributed with -# this work for additional information regarding copyright ownership. -# The ASF licenses this file to You under the Apache License, Version 2.0 -# (the "License"); you may not use this file except in compliance with -# the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# -################################################################################ - -# -# Enable or disable the refresh of the bundles when installing -# the features contained in a KAR file -# -noAutoRefreshBundles=false ----- - -By default, when the KAR deployer install features, by default, it refresh the bundles already installed. -You can disable the automatic bundles refresh by setting the `noAutoRefreshBundles` property to `false`. - -== JMX KarMBean - -On the JMX layer, you have a MBean dedicated to the management of the KAR files. - -The ObjectName to use is `org.apache.karaf:type=kar,name=*`. - -=== Attributes - -The `Kars` attributes provides the list of KAR files (name) installed. - -=== Operations - -* `install(url)` installs the KAR file at the given `url`. -* `create(repository, features)` creates a KAR file using the given features `repository` name, and optionally the -list of `features` to include in the KAR file. -* `uninstall(name)` uninstalls a KAR file with the given `name`. \ No newline at end of file
