haul 2003/01/17 06:18:03
Modified: src/documentation/xdocs/developing book.xml
Added: src/documentation/xdocs/developing web3.xml
Log:
docs for web3
Revision Changes Path
1.12 +4 -0 xml-cocoon2/src/documentation/xdocs/developing/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/developing/book.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- book.xml 1 Jul 2002 19:53:45 -0000 1.11
+++ book.xml 17 Jan 2003 14:18:02 -0000 1.12
@@ -23,6 +23,10 @@
<menu-item label="Developing Webapps" href="webapps/index.html"/>
</menu>
+ <menu label="Blocks">
+ <menu-item label="Connect to SAP R/3" href="web3.html"/>
+ </menu>
+
<menu label="Java">
<external label="API (Javadoc)" href="../apidocs/index.html"/>
</menu>
1.1 xml-cocoon2/src/documentation/xdocs/developing/web3.xml
Index: web3.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>Web3</title>
<subtitle>Web3 Connectivity Toolkit</subtitle>
<authors>
<person name="Michael Gerzabek" email="[EMAIL
PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="About">
<p>
<link href="http://www.efp.cc/web3";>EFP
Consulting Austria</link> produced an open-source library called Web3
that allows you to integrate SAP R/3 seamlessly
into Cocoon 2. With these components you are able to call Remote
Function Calls via an easy to use XML-syntax.
For most BAPIs and Remote enabled Function Calls you simply need
a text editor.
</p>
<p>This toolkit offers you ...</p>
<ul>
<li>... synchron communication to any
SAP system above release 3.1H.</li>
<li>... easy to use ABAP function calls
from outside R/3 with a se37-like markup-syntax.</li>
</ul>
<note>
The following guide helps you to setup cocoon
with your SAP R/3. Reasonably this guide cannot answer
all questions dealing with your environment.
For further questions be advised to contact your favorite SAP Consultant.
</note>
</s1>
<s1 title="Installing SAP R/3 (TM) JavaConnector">
<p>
Be sure to proper install the
appropriate SAP Java-Connector from <link
href="http://service.sap.com/connectors";>
www.sap.com</link>. To install the
connector refer to the included documentations.
</p>
</s1>
<s1 title="Configuring cocoon.xconf">
<p>
With Web3 you have a flexible Toolkit
where you can connect to multiple R/3 System within one single Cocoon-
Instance. Enter your backend
configuration into cocoon.xconf like this:
</p>
<s2 title="Items">
<table>
<caption>Configuration
elements</caption>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
<tr>
<td>web3</td>
<td>Declare your logger
here.</td>
</tr>
<tr>
<td>pool</td>
<td>The pool element is the
logical unit of all your SAP settings.</td>
</tr>
<tr>
<td>client</td>
<td>The systems client you log
onto.</td>
</tr>
<tr>
<td>user, password,
language</td>
<td>...</td>
</tr>
<tr>
<td>route</td>
<td>The route to your SAP
system. Please refer to your <link href="http://help.sap.com";>SAP help</link>
to prepare the connection string.</td>
</tr>
<tr>
<td>system</td>
<td>The system-number of your
SAP system you log onto.</td>
</tr>
<tr>
<td>gateway, program-id</td>
<td>Are mandatory and not used
within Web3's szenario.</td>
</tr>
</table>
<table>
<caption>Specifics on the <code>pool</code>
element</caption>
<tr>
<td>@trace</td><td>a <code>boolean</code> switch
whether to use JCO's facility to trace the communication layer or not.</td>
</tr>
<tr>
<td>@level</td><td>if @trace is
<code>true</code> set the trace-level to your prefered value. Please refer to
the JCO's documentation about tracing.</td>
</tr>
<tr>
<td>@size</td><td>denotes the pool-size of your sap connection pool. Be aware
that this is a hard-limited pool.</td>
</tr>
</table>
</s2>
<p>
A configuration in your cocoon.xconf would look
like this:
</p>
<source><![CDATA[<web3 logger="core.web3">
<backend name="indy">
<pool level="0" size="10" trace="false">
<client>100</client>
<user>user</user>
<password>secret-passphrase</password>
<language>DE</language>
<route>indy</route>
<system>00</system>
<gateway>sapgw00</gateway>
<program-id>USR-GR02</program-id>
</pool>
</backend>
<backend name="hugo">
...
</web3>]]></source>
</s1>
<s1 title="Test the installation">
<p>
After you configured your Web3 environment you
may want to test your connection. In SAP world there is a typical
Remote Function available called
RFC_SYSTEM_INFO. It returns some basic configuration data about your SAP-System.
To call this Remote Function point your browser
<link href="../../samples/web3/info.xml">here</link>.
</p>
</s1>
<s1 title="Implementing your own RFC's">
<p>Now that you've established your own Web3-connection
you may want to test some extra Functions. First of all you have
to setup your markup with the right Namespace</p>
<source><![CDATA[<page
xmlns:rfc="http://efp.cc/Web3-Rfc/2.0";>
...
</page>]]></source>
<p>After doing so you can enter RFC-mappings with the
following syntax. You will see this is a very easy task and you will enjoy
using Web3 to do the stuff for you within your SAP
environment :)</p>
<s2 title="Web3 rfc-Syntax">
<p>
Data definitions (metadata) are created
and managed in the ABAP Dictionary. The ABAP Dictionary permits a central
description of all the data used in the
system without redundancies. New or modified information is automatically
provided
for all the system components. This
ensures data integrity, data consistency and data security.
</p>
<p>
The syntax used within this markup
builds upon these facts. So do not wonder if you find the corresponding logical
units in the Cocoon frontend.
</p>
<table>
<caption>Markup</caption>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
<tr>
<td>
<link
href="#rfc_include">rfc:include</link>
</td>
<td>Starts a mapping for the
specified RFC.</td>
</tr>
<tr>
<td>
<link
href="#rfc_import">rfc:import</link>
</td>
<td>Container element for
structures and fields.</td>
</tr>
<tr>
<td>
<link
href="#rfc_tables">rfc:tables</link>
</td>
<td>Container element for
tables.</td>
</tr>
<tr>
<td>
<link
href="#rfc_structure">rfc:structure</link>
</td>
<td>Container element for
fields.</td>
</tr>
<tr>
<td>
<link
href="#rfc_table">rfc:table</link>
</td>
<td>Container element for
structures.</td>
</tr>
<tr>
<td>
<link
href="#rfc_field">rfc:field</link>
</td>
<td>The data-fields.</td>
</tr>
</table>
</s2>
<anchor id="rfc_include"/>
<s2 title="rfc:include">
<p>First when you start to map a RFC keep in
mind to get the parameters from your SAP system. Therefore you
may want to use se37 where all relevant
parameters are listed. The <code>@name</code> has to be the name of
the RFC you want to map. </p>
<p>Since many RFC's return hierarchical data
split into tables you will encounter some
problems in xslt when rendering these data to
trees. So you may implement
<code>org.apache.cocoon.components.web3.Web3Streamer</code> to get a proper XML
to work with. You can set your own streamer in the
<code>@streamer</code>.</p>
<table>
<caption>Attributes</caption>
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
<tr>
<td>
@name
</td>
<td>The name of the SAP RFC</td>
</tr>
<tr>
<td>
@streamer
</td>
<td>The class-name of your
function streamer. Most of the time you won't need to implement it anyway.</td>
</tr>
</table>
<p/>
</s2>
<anchor id="rfc_import"/>
<s2 title="rfc:import">
<p>
When requesting a RFC you have to fill
the import parameterlist. The import parameterlist lists all relevant parameters
that have to be provided to get proper
results from your R/3.</p>
<p>se37 can provide you with the relevant
information.
</p>
</s2>
<anchor id="rfc_tables"/>
<s2 title="rfc:tables">
<p>
Some highly complex RFC's have also
tables in their calling interface. You may need to read the SAP documentation
of the
BAPI you gotta call and when to make
use of one of them.
</p>
</s2>
<anchor id="rfc_structure"/>
<s2 title="rfc:structure">
<p>
A structure comprises fields. A field
can refer to an elementary type (via a data element or by directly specifying
the data type and length in the structure definition), another structure or a
table type. A structure can therefore be nested to any depth.
</p>
<note>At the time the facility to use
nested structures has not been tested!</note>
</s2>
<anchor id="rfc_table"/>
<s2 title="rfc:table">
<p>
A table consists of a collection of
structures with same structure type. To keep it simple we can sloppily say a
table is like
a SQL-database-table.
</p>
</s2>
<anchor id="rfc_field"/>
<s2 title="rfc:field">
<p>
Fields, also called data elements are
the smallest indivisible units of the complex types and are used to specify the
types
in structures and columns of tables. A
field describes either an elementary type or a reference type.</p>
<p>
In ABAP exist predefined types and
custom defined types. But don't worry about the horrible task of converting
into the right
type. This task is excellently done for
you by the JavaConnector.
</p>
<note>
Keep in mind that the communication
format for numbers and date is US. So supply <code>Date</code> information
in format YYYY-MM-DD with the slashes
and <code>number</code> information like DDDDD.DD where the dot is the comma!
</note>
</s2>
<p>If you want to check your RFC mappings for
syntactically correctness you may want to use the enclosed
<code>dtd</code>'s.</p>
</s1>
<s1 title="A more complex example">
<p>
The included example demonstrates a more
complex function call. Keep in mind that the correct execution
depends on the local customizing settings of
the connected SAP System.
</p>
<source><![CDATA[<page
xmlns:rfc="http://efp.cc/Web3-Rfc/1.0";>
<rfc:include name="XXX" streamer="XXX">
<rfc:import>
<rfc:structure name="XXX">
<rfc:field name="XXX">YYY</rfc:field>
<rfc:field name="XXX">YYY</rfc:field>
<rfc:field name="XXX">YYY</rfc:field>
</rfc:structure>
<rfc:tables>
<rfc:table name="XXX">
<rfc:structure name="1">
<rfc:field name="XXX">YYY</rfc:field>
<rfc:field name="XXX">YYY</rfc:field>
<rfc:field name="XXX">YYY</rfc:field>
</rfc:structure>
</rfc:table>
</rfc:tables>
</rfc:import>
</rfc:include>
</page>]]></source>
</s1>
<s1 title="Setting up the sitemap">
<p>There are two ways to setup your Web3Transformer in
the sitemap.</p>
<s2 title="Global Configuration">
<p>If you have to deal only with one R/3
Instance you may
configure your
<code>org.apache.cocoon.transformation.Web3RfcTransformer</code>
global like stated in the following sitemap
snippet.</p>
<source><![CDATA[
<map:transformer name="rfc"
src="org.apache.cocoon.transformation.Web3RfcTransformer"
logger="web3.transformation">
<system>indy</system>
</map:transformer>
]]></source>
</s2>
<s2 title="Parametrized Configuration">
<p>If you have setup several R/3 pools you can
parametrize the
<code>org.apache.cocoon.transformation.Web3RfcTransformer</code> as stated
next</p>
<source><![CDATA[
<map:transform type="rfc">
<map:parameter name="backend" value="indy"/>
</map:transform>
]]></source>
</s2>
</s1>
<s1 title="Further questions">
<p>
Enjoy using Web3. For further questions feel
free to contact the author <link href="mailto:[EMAIL PROTECTED]">Michael
Gerzabek</link>
</p>
</s1>
<figure src="images/cocoon-built.gif" alt="Built with Apache
Cocoon"/>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
