<dependency>
    <groupId>org.teiid</groupId>
    <artifactId>teiid-runtime</artifactId>
</dependency>

<dependency>
    <groupId>org.teiid</groupId>
    <artifactId>teiid-admin</artifactId>
</dependency>

<dependency>
    <groupId>org.teiid.connectors</groupId>
    <artifactId>translator-SOURCE</artifactId>
</dependency>

<dependency>
    <groupId>org.teiid.connectors</groupId>
    <artifactId>connector-SOURCE</artifactId>
</dependency>

<dependency>
    <groupId>org.teiid</groupId>
    <artifactId>teiid-runtime</artifactId>
    <exclusions>
        <exclusion>
            <groupId>net.sf.saxon</groupId>
           <artifactId>Saxon-HE</artifactId>
        </exclusion>
        <exclusion>
            <groupId>nux</groupId>
            <artifactId>nux</artifactId>
        </exclusion>
        <exclusion>
            <groupId>com.io7m.xom</groupId>
            <artifactId>xom</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.teiid</groupId>
            <artifactId>saxon-xom</artifactId>
        </exclusion>
    </exclusions>
</dependency>
---

=== Vulnerable Libraries

Prior to Teiid 8.13/8.12.2 when using the remote JDBC transport, Teiid embedded could be susceptible to deserialization exploits if it also included most versions of common-collections, older version of groovy, or spring in the classpath - see also http://www.infoq.com/news/2015/11/commons-exploit[this posting] for more details on the affected libraries.

== VDB Deployment

VDBs may be deployed in several ways in Embedded.

*VDB Metadata API*

VDB deployment can be done directly through VDB metadata objects that are the underpinning of vdb.xml deployment. Models (schemas) are deployed as a set to form a named vdb - see the `EmbeddedServer.deployVDB` method.

*XML Deployment*

Similar to a server based -vdb.xml deployment an `InputStream` may be given to a vdb.xml file - see the `EmbeddedServer.deployVDB(InputStream)` method.

*Zip Deployment*

Similar to a server based .vdb deployment a `URL` may be given to a zip file - see the `EmbeddedServer.deployVDBZip` method. The use of the zip lib for dependency loading is not enabled in Embedded.

See link:../reference/vdb_guide.adoc[VDB Guide] and link:../reference/Metadata_Repositories.adoc[Metadata Repositories] for more on a typical vdb file and zip structures. Teiid Designer 7 and later VDBs are also supported, but are subject to all of the limitations/differences highlighted in this guide.

*Translators*

Translators instances can be scoped to a VDB in AS using declarations in a vdb.xml file, however named instances in embedded are scoped to the entire `EmbeddedServer` and must be registered via the `EmbeddedServer.addTranslator` methods. Note that there are three `addTranslator` methods:

* `addTranslator(Class<? extends ExecutionFactory> clazz)` - Adds a default instance of the ExecutionFactory, using the default name either from the Translator annotation or the class name.
* `addTranslator(String name, ExecutionFactory<?, ?> ef)` - Adds a pre-initialized (ExecutionFactory.start() must have already been called) instance of the ExecutionFactory, using the given translator name.  The instance will be shared for all usage.
* `addTranslator(String name, String type, Map<String, String> properties)` - Adds a definition of an override translator - this is functionally equivalent to using a vdb.xml translator override.

A new server instance does not assume any translators are deployed and does not perform any sort of library scanning to find translators.

*Sources*

The Embedded Server will still attempt to lookup the given JNDI connection factory names via JNDI. In most non-container environments it is likely that no such bindings exist. In this case the Embedded Server instance must have `ConnectionFactoryProvider` instances manually registered, either using the `EmbeddedServer.addConnectionFactory` method, or the  `EmbeddedServer.addConnectionFactoryProvider` method to implement `ConnectionFactoryProvider` registering. Note that the Embedded Server does not have built-in pooling logic, so to make better use of a standard `java.sql.DataSource` or to enable proper use of `javax.sql.XADataSource` you must first configure the instance via a third-party connection pool.

[source,java]
.Example - Deployment

*Secured Data Sources*

If Source related security authentication, for example, if you want connect/federate/integrate Twitter supplied rest source, a security authentication is a necessary, the following steps can use to execute security authentication:

. refer to link:Secure_Embedded_with_PicketBox.adoc[Secure Embedded with PicketBox] start section to develop a SubjectFactory,
. initialize a ConnectionManager with http://ironjacamar.org/[ironjacamar] libaries, set SubjectFactory to ConnectionManager
. use the following method to create ConnectionFactory

[source,java]
.Example - Secured Data Sources

https://github.com/teiid/teiid-embedded-examples/tree/master/socialmedia-integration/twitter-as-a-datasource[twitter-as-a-datasource] is a completed example.

== Access from client applications

Typically when Teiid is deployed as Embedded Server, and if your end user application is also deployed in the same virtual machine as the Teiid Embedded, you can use *Local JDBC Connection*, to access to your virtual database. For example:

[source,java]
.Example - Local JDBC Connection

This is the most efficient method as it does not impose any serialization of objects.

If your client application is deployed in remote VM, or your client application is not a JAVA based application then accesses to the Teiid Embedded is not possible through above mechanism. In those situations, you need to open a socket based connection from remote client application to the Embedded Teiid Server. By default, when you start the Embedded Teiid Sever it does not add any capabilities to accept remote JDBC/ODBC based connections. If you would like to expose the functionality to accept remote JDBC/ODBC connection requests, then configure necessary *transports* during the initialization of the Teiid Embedded Server. The example below shows a sample code to enable a ODBC transport

[source,java]
.Example - Remote ODBC transport

[source,java]
.Example - SSL transport

if you want to add a JDBC transport, follow the instructions above, however set the protocol to `WireProtocol.teiid` and choose a different port number. Once the above server is running, you can use same link:../client-dev/Connecting_to_a_Teiid_Server.adoc[instructions] as Teiid Server to access Embedded Teiid Server from remote client application. Note that you can add multiple transports to single Embedded Server instance, to expose different transports.

== Security

The primary interface for Teiid embedded’s security is the `org.teiid.security.SecurityHelper` in the engine jar. The SecurityHelper instance is associated with with the EmbeddedServer via `EmbeddedConfiguration.setSecurityHelper`. If no SecurityHelper is set, then no authentication will be performed. A SecurityHelper controls authentication and associates a security context with a thread. How a security context is obtained can depend upon the security domain name. The default security domain name is `teiid-security` and can be changed via `EmbeddedConfiguration.setSecurityDomain`. The effective security domain may also be configured via a transport of the VDB.

See the https://github.com/teiid/teiid/blob/master/jboss-integration/src/main/java/org/teiid/jboss/JBossSecurityHelper.java[JBoss Security Helper source] for an example of expected mechanics.

You can just return null from negotiateGssLogin unless you want to all GSS authentications from JDBC/ODBC.

=== Example

https://github.com/teiid/teiid-embedded-examples/tree/master/embedded-portfolio-security[embedded-portfolio-security] demonstrates how to implement security authentication in Teiid Embedded:

* https://github.com/teiid/teiid-embedded-examples/blob/master/common/src/main/java/org/teiid/example/EmbeddedSecurityHelper.java[EmbeddedSecurityHelper] is the implementation of `org.teiid.security.SecurityHelper`
* https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/embedded-portfolio-security/src/main/resources/users.properties[users.properties] and https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/embedded-portfolio-security/src/main/resources/roles.properties[roles.properties] in class path user to pre define users and roles
* https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/common/src/main/resources/picketbox/authentication.conf[application-policy]’s name in authentication.conf should match to security domain(`EmbeddedConfiguration.setSecurityDomain`)

== Transactions

Transaction processing requires setting the `TransactionManager` in the `EmbeddedConfiguration` used to start the `EmbeddedServer`. A client facing `javax.sql.DataSource` is not provided for embedded. However the usage of provided `java.sql.Driver` should be sufficient as the embedded server is by default able to detect thread bound transactions and appropriately propagate the transaction to threads launched as part of request processing. The usage of local connections is also permitted.

== AdminApi

Embedded provides a the `Admin` interface via the `EmbeddedServer.getAdmin` method. Not all methods are implemented for embedded - for example those that deal with data sources. Also the deploy method may only deploy VDB xml artifacts.

== Logging

Teiid by default use JBoss Logging, which will utilize JUL (Java Util Logging) or other common logging frameworks depending upon their presence in the classpath. Refer to link:Logging_in_Teiid_Embedded.adoc[Logging in Teiid Embedded] for details.

The internal interface for Teiid embedded’s logging is `org.teiid.logging.Logger` in teiid-api jar. The Logger instance is associated with the `org.teiid.logging.LogManager` via static method `LogManager.setLogListener()`. You may alternatively choose to directly set a `Logger` of your choice.

== Other Differences Between Teiid Embedded and an AS Deployment

* There is no default JDBC/ODBC socket transport in embedded. You are expected to obtain a `Driver` connection via the `EmbeddedServer.getDriver` method. If you want remote JDBC/ODBC transport see above on how to add a transport.
* A `MetadataRepository` is scoped to a VDB in AS, but is scoped to the entire `EmbeddedServer` instance and must be registered via the `EmbeddedServer.addMetadataRepository` method.
* MDC logging values are not available as Java logging lacks the concept of a mapped diagnostic context.
* Translator overrides in vdb.xml files is not supported, but you may add overridden translators using the addTranslator methods that accept an ExecutionFactory instance or a property set.
* The default for the maximum disk space used by the buffer manager is 5 GB, rather than 50 GB.