= Resources
:jbake-date: 2016-03-16
:jbake-type: page
:jbake-status: published
:jbake-tomeepdf:

In TomEE resources are mainly "singleton" (understood as defined once per server or application). Technically
it can be anything but you will probably meet more Datasources than other type of resources.


Most resources will be created automatically if there is no matching resources - by name and type -
when an injection will be found. To avoid that use `openejb.offline` property and set it to `true`.
See link:server.html[Server Configuration] for more detail.

=== Definition a resource: how does it work?

Before all let see how properties syntax is equivalent to XML one (system.properties and tomee.xml typically).

Properties syntax uses dot notation to represent setters/properties which are plain properties in XML syntax
and a URL syntax with query parameters to define the resource where it is directly the resource and tag attributes in XML.
Finally the id is an attribute in XML and the key of the resource definition in properties.

Let see it with a sample, both delcarations are the same:

[source,bash]
----
myDataSource = new://Resource?type=DataSource
myDataSource.JdbcUrl = jdbc:hsqldb:mem:site
myDataSource.UserName = sa
----

[source,xml]
----
<Resource id="myDataSource" type="DataSource">
  JdbcUrl = jdbc:hsqldb:mem:site
  UserName = sa
</Resource>
----

One started you can get injected any resource using `@Resource`:

[source,java]
----
@Resource(name = "myDataSource")
private DataSource dataSource;
----

=== Factory syntax

Here are the attributes of a resource:

[.table.table-bordered,options="header"]
|===
| Name | Optional |Description
| id | false | name of the resource, will match `openejb:Resource/id` in JNDI tree.
| provider | true | define a default resource definition using service-jar.xml
| class-name | true |specify which class to instantiate
| factory-name | true |specify which method to invoke on the class-name when specified to create the resource
| properties-provider | true |a class responsible to provide to tomee the properties to use, it can have a property `serviceId` to know which resource it is.
| classpath | true | a classpath to use to create the resource. Note: if not implementing an interface the resource will be isolated from the applications.
| aliases | true | other names for the resource, allows for instance to share the same pool for a datasource used with multiple names in applications.
| post-construct/pre-destroy | true | methods called when creating/destroying the resources.
| Lazy | true | for resources set them to be created when first accessed and not when deployed
|===

TomEE supports some implicit properties for resources but sometimes you just want to fully control the
resource and not use implicit properties which can be affected to a property which doesn't expect such a value (typically the case
if you create a custom Oracle datasource). For such case you can set `SkipImplicitAttributes` property to `true` and your resource
will ignore implicit properties.

Implicit properties are:

[.table.table-bordered,options="header"]
|===
| Name | Description
| transactionManager | The JTA transaction manager
| ServiceId | the "id" of the resource (its name)
|===

In the same spirit you can skip properties fallback using `SkipPropertiesFallback` and setting it to `true`. It typically avoids to
fallback all unset properties (no matching property found) to a `Properties` instance and set it if one matching property is found.
In Oracle case for instance it matches the connection properties which can have side effects.

===== Value ciphering

The propertie values support ciphering using the syntax `cipher:{algorithm}:{cipheredValue}`, for instance `cipher:Static3DES:xMH5uM1V9vQzVUv5LG7YLA==` will
be read as `Passw0rd`. Ciphers can be computed using `tomee.sh` script: `${tomee.home}/bin/tomee.sh cipher Passw0rd`.

=== Common Resources

==== DataSources

DataSources have defaults for all values and a default datasource can be provided automatically but if you want to
configure it here are the common properties:

You can set the boolean `JtaManaged` to false if you don't want your datasource to be using JTA - if you manage transactions yourself.

Then other configurations are linked the pool the datasource is using. By default TomEE uses https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html[tomcat-jdbc] but we also provide
https://commons.apache.org/proper/commons-dbcp/configuration.html[commons-dbcp] (2 for TomEE 7.x and 1 for TomEE 1.x).
The properties are then the related configurations with these particular
entries we try to keep in sync for both:

[.table.table-bordered,options="header"]
|===
| Name|Description
| JdbcDriver | the jdbc driver of the datasource
| JdbcUrl | the jdbc url of the datasource
| Username | the user to use
| Password | the password of the user
|===

===== Password and ciphering

DataSource were the first resource to support password ciphering. Originally it was another property which is still supported.
It is called `PasswordCipher`. Its value is the ciphering algorithm and it affects the password value. However `cipher:xxx`
is still supported on `Password` value. Default `PasswordCipher` being `PlainText` it behaves as no ciphering is in place by default.

Sample:

[source,bash]
----
ds = new://Resource?type=javax.sql.DataSource
# our password is "Passw0rd"
ds.Password = xMH5uM1V9vQzVUv5LG7YLA==
ds.PasswordCipher = Static3DES
----

===== Advanced DataSource configuration

TomEE also provides few utilities you can add in DataSource properties:

[.table.table-bordered,options="header"]
|===
| Name | Description
| LogSql | Should SQL be logged (using TomEE logger)
| LogSqlPackages | if set the logging will show the matching packages (separated by comma) inline when logging the query, allows to know where a query comes from
| Flushable| if true the datasource can be casted as a Flushable to recreate the pool
| ResetOnError | if a `SQLException` happens the pool is automatically recreated. Configuration is either "true" to do it each time an exception occurs, `x` or `retry(x)` to do it and retry until maximum `x` times
| ResetOnErrorMethods | which methods are handled by ResetOnError
| TomEEProxyHandler | Custom `InvocationHandler` wrapping the datasource calls
| DataSourceCreator | which pool to use, `dbcp`, `tomcat`, `dbcp-alternative` (DBCP and TomEE proxying instead of DBCP JTA integration), `simple` (no pooling)
|===

===== DataSource and JTA

`JtaManaged` determines wether or not this data source should be JTA managed
or user managed.  If set to 'true' it will automatically be enrolled
in any ongoing transactions.  Calling begin/commit/rollback or setAutoCommit
on the datasource or connection will not be allowed.  If you need to perform
these functions yourself, set `JtaManaged` to `false`

===== DataSource and JPA

In terms of JPA persistence.xml:

- `JtaManaged=true` can be used as a 'jta-data-source'
- `JtaManaged=false` can be used as a 'non-jta-data-source'

=== ActiveMQResourceAdapter

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="ActiveMQResourceAdapter">
    BrokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false
    ServerUrl = vm://localhost?waitForStart=20000&async=true
    DataSource = Default Unmanaged JDBC Database
    StartupTimeout = 10 seconds
</Resource>
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=ActiveMQResourceAdapter
Foo.BrokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false
Foo.ServerUrl = vm://localhost?waitForStart=20000&async=true
Foo.DataSource = Default Unmanaged JDBC Database
Foo.StartupTimeout = 10 seconds
----

==== Configuration

===== BrokerXmlConfig

Broker configuration URI as defined by ActiveMQ
see http://activemq.apache.org/broker-configuration-uri.html
BrokerXmlConfig xbean:file:conf/activemq.xml - Requires xbean-spring.jar and dependencies

===== ServerUrl

Broker address

===== DataSource

DataSource for persistence messages

===== StartupTimeout

How long to wait for broker startup


=== javax.jms.ConnectionFactory

An ActiveMQ (JMS) connection factory.

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="javax.jms.ConnectionFactory">
    ResourceAdapter = Default JMS Resource Adapter
    TransactionSupport = xa
    PoolMaxSize = 10
    PoolMinSize = 0
    ConnectionMaxWaitTime = 5 seconds
    ConnectionMaxIdleTime = 15 Minutes
</Resource>
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=javax.jms.ConnectionFactory
Foo.ResourceAdapter = Default JMS Resource Adapter
Foo.TransactionSupport = xa
Foo.PoolMaxSize = 10
Foo.PoolMinSize = 0
Foo.ConnectionMaxWaitTime = 5 seconds
Foo.ConnectionMaxIdleTime = 15 Minutes
----

==== Configuration

===== ResourceAdapter

An ActiveMQ (JMS) resource adapter.

===== TransactionSupport

Specifies if the connection is enrolled in global transaction
allowed values: `xa`, `local` or `none`. Default to `xa`.

===== PoolMaxSize

Maximum number of physical connection to the ActiveMQ broker.

===== PoolMinSize

Minimum number of physical connection to the ActiveMQ broker.

===== ConnectionMaxWaitTime

Maximum amount of time to wait for a connection.

===== ConnectionMaxIdleTime

Maximum amount of time a connection can be idle before being reclaimed.


=== javax.jms.Queue

An ActiveMQ (JMS) queue.

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="javax.jms.Queue">
    # not set means id
    destination =
</Resource>
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=javax.jms.Queue
# not set means id
Foo.destination =
----

==== Configuration

===== destination

Specifies the name of the queue


=== javax.jms.Topic

An ActiveMQ (JMS) topic.

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="javax.jms.Topic">
    # not set means id
    destination =
</Resource>
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=javax.jms.Topic
# not set means id
Foo.destination =
----

==== Configuration

===== destination

Specifies the name of the topic


=== org.omg.CORBA.ORB

NOTE: to use it you need to add an implementation of corba.

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="org.omg.CORBA.ORB" />
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=org.omg.CORBA.ORB
----


=== javax.mail.Session

A mail session.

Declarable in tomee.xml via

[source,xml]
----
<Resource id="mail/mysession" type="javax.mail.Session">
  mail.transport.protocol = smtp
  mail.smtp.host = smtp.provider.com
  mail.smtp.auth = true
  mail.smtp.starttls.enable = true
  mail.smtp.port = 587
  mail.smtp.user = user@provider.com
  password = abcdefghij
</Resource>
----

Declarable in properties via

[source,bash]
----
mail/mysession = new://Resource?type=javax.mail.Session
mail/mysession.mail.transport.protocol = smtp
mail/mysession.mail.smtp.host = smtp.provider.com
mail/mysession.mail.smtp.auth = true
mail/mysession.mail.smtp.starttls.enable = true
mail/mysession.mail.smtp.port = 587
mail/mysession.mail.smtp.user = user@provider.com
mail/mysession.password = abcdefghij
----

The properties are `javax.mail.Session` ones with the addition of `useDefault` which specifies if `getDefaultInstance()`
or `getInstance` is used to create the session. `getDefaultInstance()` will ensure that several calls are done with the
same configuration and return the same instance. For tomee it is likely better to rely on `getInstance()`(ie keep `useDefault` to false)
and use `aliases` option of the resource to define an alias if you need to share the same instance accross multiple names.


=== ManagedExecutorService

A concurrency utility for EE executor service.

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="ManagedExecutorService">
    Core = 5
    Max = 25
    KeepAlive = 5 s
    Queue = 15
    ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl
    Lazy = true
</Resource>
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=ManagedExecutorService
Foo.Core = 5
Foo.Max = 25
Foo.KeepAlive = 5 s
Foo.Queue = 15
Foo.ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl
Foo.Lazy = true
----

==== Configuration

===== Core

The pool core size.

===== Max

The pool max size.

===== KeepAlive

The thread keep alive time (in duration format)

===== Queue

The queue type size.

===== ThreadFactory

The thread factory implementation class.

===== Lazy

If set to true the pool is created when first accessed otherwise it is created at startup.


=== ManagedScheduledExecutorService

Inherit from `ManagedExecutorService` and adds scheduling abilities.

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="ManagedScheduledExecutorService">
    Core = 5
    ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl
    Lazy = true
</Resource>
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=ManagedScheduledExecutorService
Foo.Core = 5
Foo.ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl
Foo.Lazy = true
----

==== Configuration

See `ManagedExecutorService`.


=== ManagedThreadFactory

A thread factory for a `ManagedExecutorService`.

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="ManagedThreadFactory">
    Prefix = openejb-managed-thread-
    Lazy = true
</Resource>
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=ManagedThreadFactory
Foo.Prefix = openejb-managed-thread-
Foo.Lazy = true
----

==== Configuration

===== Prefix

The thread prefix (suffixed with thread id).


=== ContextService

A concurrency utilities for JavaEE context service. It allows to create
contextual proxies (inheriting from security, classloader...contexts).

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="ContextService" />
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=ContextService
----


=== JndiProvider: inject remote clients

A thread factory for a `ManagedExecutorService`.
Default implementation is `org.apache.openejb.threads.impl.ManagedThreadFactoryImpl`.

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="ManagedThreadFactory">
    Prefix = openejb-managed-thread-
    Lazy = true
</Resource>
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=ManagedThreadFactory
Foo.Prefix = openejb-managed-thread-
Foo.Lazy = true
----

==== Configuration

===== Prefix

The thread prefix (suffixed with thread id).


=== ContextService

A concurrency utilities for JavaEE context service. It allows to create
contextual proxies (inheriting from security, classloader...contexts).

Declarable in tomee.xml via

[source,xml]
----
<Resource id="Foo" type="ContextService" />
----

Declarable in properties via

[source,bash]
----
Foo = new://Resource?type=ContextService
----