[JBTM-1593] Introduce top level READMEs

ArjunaCore/README.md

@@ -0,0 +1,13 @@
+
+OVERVIEW
+--------
+ArjunaCore is the core of Narayana providing a fully functional transaction engine (TxCore) and Transactional Objects for Java (TXOJ). It is multi-threaded, distributed, supports nested transactions, fault tolerance/recovery and permits relaxation of subsets of the standard ACID transaction properties.
+
+TXOJ provides desirable features such as concurrency control, state management and persistence.
+
+All the quickstarts related to ArjunaCore are found in this folder structure. Each quickstart has a readme.txt to show how to execute the quickstart and what is happening in it. Each quickstart also contains a script to run the quickstart automatically and check the result automatically.
+
+
+USAGE
+-----
+cd into the required quickstart and follow the readme.txt or call the run.[sh|bat] file

ArjunaJTA/README.md

@@ -0,0 +1,41 @@
+
+OVERVIEW
+--------
+ArjunaJTA is a layer on top of ArjunaCore (which is a general purpose transaction engine and not tied to any particular standard) and provides full non-distributed implementation of the JTA standard.
+
+These quickstarts showcase the various ways of using JTA: 
+
+maven
+-----
+
+A minimal maven project which shows how to include the narayana JTA artifact and how to begin and end a JTA style transaction
+
+javax transaction
+-----------------
+
+Basic example showing how to use the standard JTA APIs
+
+JEE Transactional App
+-----------------
+
+A more advanced example demonstrating how to build transactional JEE applications
+
+Standalone JTA 1_2
+-----------------
+
+JTA 1.2 introduces new annotations for controlling the transactional behaviour of CDI beans. The standalone-jta-1_2 quickstart indicate how to take advantage of these annotations in a standalone application (ie in environments where a JEE container is either not available or is undesirable) 
+
+Object Store
+-----------------
+
+The JTA transaction engine must persist information about participants during transaction processing in order to guarantee ACID semantics in the event of failures. Narayana provides a number of storage mechanisms whith varying characteristics. The object store quickstarts show how to configure these various stores.
+
+Recovery
+-----------------
+
+An important property of transaction systems is the guarantee of consistent state in the present of varous type of failure. The recovery quickstarts include a number of examples that demonstrated how the narayana transaction manager possesses this property.
+
+
+USAGE
+-----
+cd into the required quickstart and follow the readme.txt or call the run.[sh|bat] file

ArjunaJTS/README.md

@@ -0,0 +1,30 @@
+
+OVERVIEW
+--------
+The Java Transaction Service (JTS) is the JEE specification for performing distributed transactions and "supports the JTA specification at the high-level and implements the Java mapping of the OMG Object Transaction Service (OTS) 1.1 Specification at the low-level" (quote from the JEE spec). Our implementation of JTS builds on ArjunaCore adding distributed operations and failure recovery. In addition to standards conformance the implementation adds optional capabilities such as nested transactions and interoposition.
+
+Here you will find a number of quickstarts showcasing JTS: 
+
+JTS
+-----------------
+
+JEE example showing how to make transactional EJB calls between multiple containers. This quickstart builds on the jta quickstart in the same folder.
+
+JTA
+-----------------
+
+Introduces the JTA concepts used in the previous JTS quickstart for the purpose of clarifying what additional steps the application developer needs to apply to make remote EJBs calls transactional.
+
+Recovery
+-----------------
+
+Shows standalone JTS (ie the example does not require a JEE application server) and demonstrates how to perform distributed recovery of failed transactions.
+
+Trailmap
+-----------
+
+The trail map will help you get started with running Narayna transaction service product in standalone mode and includes a section on jts. The map should be followed in conjunction with the [JTS developers guide](http://docs.jboss.org/jbosstm/latest/guides/narayana-jts-development_guide/index.html#d0e4340)
+
+USAGE
+-----
+cd into the required quickstart and follow the readme.txt or README.md file

atsintegration/README.md

@@ -0,0 +1,6 @@
+
+OVERVIEW
+--------
+
+Using Narayana inside a JEE application server requires an integration layer. The code in this directory tree includes some example code we have used to test new features of distributed transactions inside the wildfly application server. It is provided here for information.
+

blacktie/README.md

@@ -0,0 +1,48 @@
+
+OVERVIEW
+--------
+
+BlackTie is an [XATMI](http://pubs.opengroup.org/onlinepubs/9694999399/toc.pdf) implmentation. XATMI is a set of APIs for writing distributed client/server applications. BlackTie bridges the gap between JEE and XATMI and provides the tools to allow existing XATMI application programs written in C/C++ to integrate seamlessly into the wildfly/JBoss stack allowing these applications to migrate easily to the services provided by the wildfly application server. As well as providing C++ APIs to support the X/Open XATMI specification, Blacktie also provides the JAtmiBroker API to support clients and services written in Java. Here you find a variety of quickstarts to get you started using BlackTie
+
+xatmi
+-----
+
+Quickstarts relating to the XATMI standard such as security, interacting with databases, making remote service calls, using queues and topics. This is the best place to start to get a basic understanding of BlackTie and XATMI.
+
+blacktie-admin-services
+-----------------------
+
+Shows how to use the admin server to perform various administrative operatons on BlackTie domains and servers such as:
+- listing servers in a domain
+- Halt servers, update configuration, restart
+- pause and resume a domain
+- etc
+
+- listing services
+- advertising/unadvertising services
+- stopping/starting servers
+- etc
+
+integration1
+------------
+
+Shows how a C client can invoke an XATMI service and an EJB within the scope of the same transaction
+
+jatmibroker
+-----------
+
+An example of how to use Java based XATMI services
+
+messaging
+---------
+
+Demonstrates messaging support in BlackTie
+
+nbf
+---
+
+Shows how to use Nested Buffers for using complex datatypes in services
+
+USAGE
+-----
+cd into the relevant quickstart directory and browse the readme file.

jca-and-tomcat/README.md

@@ -1,4 +1,4 @@
-Example JBoss Transactions, Iron Jacamar, and Tomcat.
+Example Narayana Transactions, Iron Jacamar, and Tomcat.
 ==================================================================================================
 Author: Gytis Trikleris;
 Level: Intermediate;
@@ -7,7 +7,7 @@ Technologies: JTA, JCA, Tomcat
 What is it?
 -----------
 
-This example demonstrates how to integrate JBossTS, IronJacamar, and Tomcat.
+This example demonstrates how to integrate Narayana, IronJacamar, and Tomcat.
 The code is based on _JTA_ and _cmt_ quickstarts.
 
 Embedded IronJacamar container is used in this quickstart. All its dependencies can be found in pom.xml.

rts/README.md

@@ -0,0 +1,10 @@
+
+OVERVIEW
+--------
+
+Examples showing how to use transactions in a REST based design
+
+at (REST Atomic Transactions)
+--
+
+Quickstarts that show the atomic transactions (as opposed to other models such as compensation based).