From teiid-commits at lists.jboss.org Mon Jun 28 10:47:11 2010
Content-Type: multipart/mixed; boundary="===============2767256870481255312=="
MIME-Version: 1.0
From: teiid-commits at lists.jboss.org
To: teiid-commits at lists.jboss.org
Subject: [teiid-commits] teiid SVN: r2309 - in branches/7.0.x:
 documentation/admin-guide/src/main/docbook/en-US/content and 2 other
 directories.
Date: Mon, 28 Jun 2010 10:47:11 -0400
Message-ID: <201006281447.o5SElBfi006729@svn01.web.mwc.hst.phx2.redhat.com>

--===============2767256870481255312==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: shawkins
Date: 2010-06-28 10:47:10 -0400 (Mon, 28 Jun 2010)
New Revision: 2309

Added:
   branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/=
performance.xml
   branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/en=
titlements.xml
Modified:
   branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java
   branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/=
security.xml
   branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference.=
xml
Log:
adding doc content and correcting javadoc

Modified: branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement=
.java
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java	=
2010-06-28 14:43:04 UTC (rev 2308)
+++ branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java	=
2010-06-28 14:47:10 UTC (rev 2309)
@@ -64,7 +64,7 @@
     /**
      * Obtain the query planner debug log from the last command =

      * executed on this Statement, if it was requested with
-     * OPTION DEBUG.  If no debug output was requested, this =

+     * SHOWPLAN DEBUG.  If no debug output was requested, this =

      * method will return null. =

      * @return Debug log or null if no log exists
      */

Added: branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/cont=
ent/performance.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content=
/performance.xml	                        (rev 0)
+++ branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content=
/performance.xml	2010-06-28 14:47:10 UTC (rev 2309)
@@ -0,0 +1,28 @@
+<!-- =

+TODO: incorporate a performance chapter.
+
+The information about document materialization belongs in the reference th=
ough.  And is not completely correct
+w.r.t. the use of document projection.
+
+        <para>Your application can use a statement object to execute queri=
es that return XML documents.  =

+        The query must specify a valid document in VDB, or should have use=
d SQL XML functions =

+        to create a XMl document.</para>
+        <sect3>
+            <title>XML Streaming</title>
+            <para>XML documents are streamed from Teiid Server to the Teii=
d JDBC API.=C2=A0=C2=A0 =

+            Normally, the document never materializes in the server memory=
, avoiding potential =

+            out-of-memory issues and improving the first response time for=
 large documents. =

+            When using style sheets, or XQuery, the whole document =

+            must be materialized on the server.  Therefore memory issues m=
ay occur for large documents. =

+            A result document can be obtained from the JDBC resultset usin=
g <code>getSQLXML</code> method.
+            </para>
+            <para>The document is broken into pieces when being created an=
d streamed.=C2=A0 =

+            The maximum size of each piece in the stream can be configured=
 with the =

+            <code>"lobChunkSizeInKB"</code> system property on the Server.=
 The default value is 100 KB.=C2=A0 =

+            At any given time, this is the maximum amount of memory that c=
an be held by a particular =

+            XML query against the system.=C2=A0 In heavily loaded or memor=
y-constrained scenarios, =

+            this value can decrease the amount of memory used.=C2=A0 As a =
side effect, streaming will occur in smaller pieces, reducing initial docum=
ent response time while =

+            increasing full response time (as this is less efficient).</pa=
ra>
+        </sect3>
+        =

+ -->
\ No newline at end of file


Property changes on: branches/7.0.x/documentation/admin-guide/src/main/docb=
ook/en-US/content/performance.xml
___________________________________________________________________
Name: svn:mime-type
   + text/plain

Modified: branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/c=
ontent/security.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content=
/security.xml	2010-06-28 14:43:04 UTC (rev 2308)
+++ branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content=
/security.xml	2010-06-28 14:47:10 UTC (rev 2309)
@@ -3,7 +3,7 @@
 <chapter id=3D"custom_security">
 	<title>Teiid Security</title>
 	<para>The Teiid system provides a range of built-in and extensible securi=
ty features to enable the
-		secure access of data. =C2=A0</para>
+		secure access of data.</para>
 	<sect1>
 		<title>Authentication</title>
 		<para>JDBC clients may use simple passwords to authenticate a user.</par=
a>
@@ -11,6 +11,13 @@
 			identity of the user can be discerned by the password credential alone.=
 =C2=A0In
 			any case it is up to the configured security domain to determine whethe=
r a user can be
 			authenticated.</para>
+			=

+			<note><para>By default, access to Teiid is NOT secure. The default logi=
n modules are only =

+	        backed by file based authentication, which has a well known user =

+	        name and password.
+	        The same is true for making connections to the Admin Console appl=
ication. =

+	        We DO NOT recommend leaving the default security profile as defin=
ed when you =

+	        are exposing sensitive data.</para></note>
 	</sect1>
 	<sect1>
 		<title>Authorization</title>
@@ -59,6 +66,14 @@
 			Details of the failed attempt including invalid users, which
 			domains were consulted, etc. will be in the server log with appropriate
 			levels of severity.</para>
+			    <note>
+        <para>The security-domain defined for the JDBC connection and Admi=
n connections are separate.
+            The default name of JDBC connection's security-domain is "teii=
d-security". The default name for Admin connection
+            is "jmx-console". For the Admin connection's security domain, =
the user is allowed =

+            to change which LoginModule that "jmx-console" pointing to, ho=
wever should not change the name of the domain, as this name is
+            shared between the "admin-console" application.</para>
+    </note>    =

+			=

 		<sect2>
 			<title>Built-in LoginModules</title>
 			<para>JBossAS provides several LoginModules for common authentication n=
eeds, such as authenticating from text files or LDAP.</para>
@@ -71,12 +86,52 @@
             If you want use a your own Custom Login module, check out the =
Developer's Guide for instructions.
 	        </para>
 		</sect2>
+		=

 	</sect1>
-    <note>
-        <para>The security-domain defined for the JDBC connection and Admi=
n connections are separate.
-            The default name of JDBC connection's security-domain is "teii=
d-security". The default name for Admin connection
-            is "jmx-console". For the Admin connection's security domain, =
the user is allowed =

-            to change which LoginModule that "jmx-console" pointing to, ho=
wever should not change the name of the domain, as this name is
-            shared between the "admin-console" application.</para>
-    </note>    =

+	=

+	<sect1 id=3D"connfigure_server">
+        <title>Configuring SSL</title>
+        <para>The Teiid's configuration file =

+        <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/deploy/teiid/te=
iid-jboss-beans.xml</code>, =

+        contains the properties to configure SSL.</para>
+        <itemizedlist>
+        	<para>There are two separate connection profiles:</para>
+            <listitem><para>JDBC Connection - The <code>JdbcSslConfigurati=
on</code> bean configuration defines this.</para></listitem>
+            <listitem><para>Admin Connection - The <code>AdminSslConfigura=
tion</code> bean configuration defines this.</para></listitem>
+        </itemizedlist>
+        <example><title>Example Configuration</title>
+	    <programlisting><![CDATA[<bean name=3D"JdbcSslConfiguration" class=3D=
"org.teiid.transport.SSLConfiguration">
+    <property name=3D"sslEnabled">false</property>
+    <property name=3D"keystoreFilename">cert.keystore</property>
+    <property name=3D"keystorePassword">passwd</property>
+    <property name=3D"keystoreType">JKS</property>
+    <property name=3D"sslProtocol">SSLv3</property>
+    <property name=3D"keymanagementAlgorithm">false</property>
+    <property name=3D"truststoreFilename">cert.truststore</property>
+    <property name=3D"truststorePassword">passwd</property>
+    <!--  1-way, 2-way, anonymous -->
+    <property name=3D"authenticationMode">1-way</property>
+    <property name=3D"clientEncryptionEnabled">true</property>
+</bean>]]></programlisting>       =

+</example>
+           <orderedlist>
+           	<title>Properties</title>
+            <listitem><para>sslEnabled - true|false, SSL usage either turn=
ed ON or OFF </para></listitem>
+            <listitem><para>sslProtocol- Type of SSL protocol to be used. =
Default is SSLv3</para></listitem>
+            <listitem><para>keystoreType - Keystore type created by the ke=
ytool. Default "JKS" is used.</para></listitem>
+            <listitem><para>authenticationMode - anonymous|1-way|2-way,  T=
ype of SSL mode, see  =

+            above about different <link linkend=3D"ssl_modes">SSL modes</l=
ink> available.</para></listitem>
+            <listitem><para>keymanagementAlgorithm - Type of key algorithm=
 used. Default =

+            is based upon the VM, e.g. "SunX509"</para></listitem>
+            <listitem><para>keystoreFilename - The file name of the keysto=
re, which contains the =

+            private key of the Server. This must be available in the class=
path of Teiid Server</para></listitem>
+            <listitem><para>keystorePassword - password for the keystore.<=
/para></listitem>
+            <listitem><para>truststoreFilename - if "authenticationMode" i=
s chosen =

+            as "2-way", then this property must be provided. This is the t=
ruststore that contains the =

+            public key for the client. Depending upon how you created the =
keystore and truststores, =

+            this may be same file as defined under  "keystoreFilename" pro=
perty.</para></listitem>
+            <listitem><para>truststorePassword - password for the truststo=
re. </para></listitem>
+           </orderedlist>  =

+           =

+    </sect1>
 </chapter>
\ No newline at end of file

Modified: branches/7.0.x/documentation/reference/src/main/docbook/en-US/Ref=
erence.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference=
.xml	2010-06-28 14:43:04 UTC (rev 2308)
+++ branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference=
.xml	2010-06-28 14:47:10 UTC (rev 2309)
@@ -53,6 +53,7 @@
   <xi:include href=3D"content/scalar_functions.xml" xmlns:xi=3D"http://www=
.w3.org/2001/XInclude" />
   <xi:include href=3D"content/procedures.xml" xmlns:xi=3D"http://www.w3.or=
g/2001/XInclude" />
   <xi:include href=3D"content/transaction_support.xml" xmlns:xi=3D"http://=
www.w3.org/2001/XInclude" />
+  <xi:include href=3D"content/entitlements.xml" xmlns:xi=3D"http://www.w3.=
org/2001/XInclude" />
   <xi:include href=3D"content/system_schema.xml" xmlns:xi=3D"http://www.w3=
.org/2001/XInclude" />
   <xi:include href=3D"content/translators.xml" xmlns:xi=3D"http://www.w3.o=
rg/2001/XInclude" />
   <xi:include href=3D"content/federated_planning.xml" xmlns:xi=3D"http://w=
ww.w3.org/2001/XInclude" />

Added: branches/7.0.x/documentation/reference/src/main/docbook/en-US/conten=
t/entitlements.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/e=
ntitlements.xml	                        (rev 0)
+++ branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/e=
ntitlements.xml	2010-06-28 14:47:10 UTC (rev 2309)
@@ -0,0 +1,122 @@
+<?xml version=3D"1.0" encoding=3D"UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.=
oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
+%CustomDTD;
+]>
+<chapter id=3D"entitlements">
+    <title>Data Roles</title>
+    <para>Data roles, also called entitlements, are sets of permissions th=
at are defined =

+    per VDB that dictate data access (create, read,  update, delete). The =
use of data roles is controlled system wide with the property in =

+    <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/deploy/teiid/teiid-=
jboss-beans.xml</code> file
+    in bean configuration section of <code>RuntimeEngineDeployer</code> wi=
th property <code>useEntitlements</code>.</para>
+    =

+    <para>Once data roles are enabled, the access permissions defined in a=
 VDB will be enforced by the Teiid Server.</para>
+    =

+    <sect1>
+    	<title>Permissions</title>
+   	    <orderedlist>
+	        <para>To process a <code>SELECT</code> statement or a stored proc=
edure execution, the user account requires the following access rights:</pa=
ra>
+	        <listitem> <para><code>READ</code> - on the Table(s) being access=
ed or the procedure being called.</para></listitem>
+	        <listitem> <para><code>READ</code> - on every column referenced.<=
/para></listitem>
+	    </orderedlist>   =

+	    =

+	    <orderedlist>
+	        <para>To process an <code>INSERT</code> statement, the user accou=
nt requires the following access rights:</para>
+	        <listitem> <para><code>CREATE</code> - on the Table being inserte=
d into.</para></listitem>
+	        <listitem> <para><code>CREATE</code> - on every column being inse=
rted on that Table.</para></listitem>
+	    </orderedlist>   =

+	    =

+	    <orderedlist>
+	        <para>To process an <code>UPDATE</code> statement, the user accou=
nt requires the following access rights:</para>
+	        <listitem> <para><code>UPDATE</code> - on the Table being updated=
.</para></listitem>
+	        <listitem> <para><code>UPDATE</code> - on every column being upda=
ted on that Table.</para></listitem>
+	        <listitem> <para><code>READ</code> - on every column referenced i=
n the criteria.</para></listitem>
+	    </orderedlist>    =

+	    =

+	    <orderedlist>
+	    	<para>To process a <code>DELETE</code> statement, the user account r=
equires the following access rights:</para>
+	        <listitem> <para><code>DELETE</code> - on the Table being deleted=
.</para></listitem>
+	        <listitem> <para><code>READ</code> - on every column referenced i=
n the criteria.</para></listitem>
+	    </orderedlist>    =

+    </sect1>
+
+	<sect1>
+		<title>XML Definition</title>
+	    <para>Data roles are defined inside the <code>vdb.xml</code> file (in=
side the .vdb Zip archive under META-INF/vdb.xml) if you used Designer. =

+    This example will show a sample "vdb.xml" file with few simple data ru=
les.</para>
+    =

+    <para>For example, if a VDB defines a table "TableA" in schema "modelN=
ame" with columns (column1, column2) - note that the column types do not ma=
tter.  And we wish to define three roles "RoleA", "RoleB", "RoleC" with fol=
lowing permissions:
+   <orderedlist>
+    <listitem><para>RoleA has privileges to read, write access to TableA, =
but can not delete.</para></listitem>
+    <listitem><para>RoleB has no privileges that allow access to TableA</p=
ara></listitem>
+    <listitem><para>RoleC has privileges that only allow read access to Ta=
bleA.column1</para></listitem>
+   </orderedlist>
+	</para>
+    <example><title>vdb.xml defining RoleA, RoleB, and RoleC</title>
+   <programlisting><![CDATA[<?xml version=3D"1.0" encoding=3D"UTF-8"?>
+<vdb name=3D"sample" version=3D"1">
+
+    <model name=3D"modelName">
+        <source name=3D"source-name" translator-name=3D"oracle" connection=
-jndi-name=3D"java:myDS" />
+    </model>
+
+    <data-policy name=3D"RoleA">
+        <description>Allow all, except Delete</description>
+
+        <permission>
+            <resource-name>modelName.TableA</resource-name>
+            <allow-create />
+            <allow-read />
+            <allow-update />
+        </permission>
+
+        <permission>
+            <resource-name>modelName.TableA.colum1</resource-name>
+            <allow-create />
+            <allow-read />
+            <allow-update />
+        </permission>
+
+        <permission>
+            <resource-name>modelName.TableA.column2</resource-name>
+            <allow-create />
+            <allow-read />
+            <allow-update />
+        </permission>
+
+        <mapped-role-name>role1</mapped-role-name>
+
+    </data-policy>
+
+    <data-policy name=3D"RoleC">
+        <description>Allow read only</description>
+
+        <permission>
+            <resource-name>modelName.TableA</resource-name>
+            <allow-read />
+        </permission>
+
+        <permission>
+            <resource-name>modelName.TableA.colum1</resource-name>
+            <allow-read />
+        </permission>
+
+        <mapped-role-name>role2</mapped-role-name>
+    </data-policy>
+</vdb>]]></programlisting>    =

+</example>   =

+   <para>The above XML defined two data roles, "RoleA" which allows everyt=
hing except delete on the table, "RoleC" that =

+   allows only read operation on the table. Since Teiid uses deny by defau=
lt, there is no explict data-policy entry needed for "RoleB".  The "mapped-=
role-name" defines the "role" to whom these policies are applicable. Each d=
ata-policy =

+   must define a "role" to be enforced by the Teiid Server.</para>
+   =

+   <para>For assigning the roles to your users, in the JBoss AS, =

+   check out the instructions for the selected Login Module. Check "Admin =
Guide" for configuring Login Modules.</para> =

+   =

+   <para>"vdb.xml" file is checked against the schema file <code>vdb-deplo=
yer.xsd</code>, check the documents sections of the Teiid kit
+   to find a copy of the schema file.</para>
+   =

+   <note><para>Currently there is no GUI tooling support in the Designer o=
r any other management tool to create this data roles =

+   permissions xml, however this is in our roadmap for future releases to =
provide.</para></note>
+	</sect1>
+
+</chapter>
\ No newline at end of file


Property changes on: branches/7.0.x/documentation/reference/src/main/docboo=
k/en-US/content/entitlements.xml
___________________________________________________________________
Name: svn:mime-type
   + text/plain


--===============2767256870481255312==--