| = 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 |
| ---- |
| |
| |