You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tomee.apache.org by jg...@apache.org on 2015/04/15 23:08:24 UTC
svn commit: r1673959 - /tomee/site/trunk/content/application-resources.mdtext
Author: jgallimore
Date: Wed Apr 15 21:08:23 2015
New Revision: 1673959
URL: http://svn.apache.org/r1673959
Log:
Adding more Resource documentation
Modified:
tomee/site/trunk/content/application-resources.mdtext
Modified: tomee/site/trunk/content/application-resources.mdtext
URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/application-resources.mdtext?rev=1673959&r1=1673958&r2=1673959&view=diff
==============================================================================
--- tomee/site/trunk/content/application-resources.mdtext (original)
+++ tomee/site/trunk/content/application-resources.mdtext Wed Apr 15 21:08:23 2015
@@ -3,15 +3,15 @@ Title: Application Resources
# Resources
-TomEE provides the means to define resources in the server in the `conf/tomee.xml` file. These resources are created when the server boots up, and can be injected into managed components inside your application.
+TomEE provides a simple but powerful way to define resources that can be injected into managed components inside your application, or looked up via JNDI. To use a resource, it needs to be defined in the `tomee.xml` configuration file, a `resources.xml` file within an application, or as a system property. Defining a resource in `tomee.xml` will make it available server-wide, whereas defining the resource within a `resources.xml` file makes it available to a specific application.
-For example, you can define a JMS queue in `tomee.xml` with the following configuration:
+As a simple example, a JMS queue can be defined within `tomee.xml` with the following configuration.
<tomee>
<Resource id="MyQueue" type="javax.jms.Queue"/>
</tomee>
-And inject it into the field of a class using `@Resource`:
+Once the resource has been defined, the server will create an instance of the resource during startup, and it will be available to be injected into managed components using the `@Resource` annotation, as shown below. The `name` attribute on the `@Resource` annotation should match the `id` attribute on the `Resource` tag.
public class JmsClient {
@@ -24,67 +24,89 @@ And inject it into the field of a class
}
-# Custom resources
+As an alternative to defining a resource in XML, resources can also be defined using system properties:
+
+ MyQueue = new://Resource?type=javax.jms.Queue
+
+Resources, or attributes for resources specified using system properties will override definitions specified in `tomee.xml`.
+Server-wide resources can be looked up in JNDI under the following name: openejb:Resources/<resource id>.
-In addition to this, TomEE also allow you to define your own Java classes to use as resources, and these can also be injected into managed components in the same way.
+# Defining Resources
+<a name="DefiningResources"></a>
-So the following simple resource
+The `<Resource>` tag has a number of attributes, and a resource may also have a number of fields that can be configured by adding properties to the body of the `Resource` tag.
- public class Greeter {
+For example, a DataSource resource needs a JDBC driver, URL, username and password to be able to connect to a database. That would be configured with the following syntax. Notice the key/value pair syntax for the properties within the `<Resource>` tag.
+
+ <Resource id="DB" type="DataSource">
+ JdbcDriver com.mysql.jdbc.Driver
+ JdbcUrl jdbc:mysql://localhost/test
+ UserName test
+ Password password
+ </Resource>
- public String greet(final String name) {
- return "Hello, " + name;
- }
+Specifying the key/value pairs specific to a Resource can also be done when defining the resource via system properties. This is done be specifying an additional property for each key/value pair, using the resource ID as a prefix: `<resourceId>.<propertyName>=<value>`. The system properties equivalent of the resource above is:
+
+ p.setProperty("DB", "new://Resource?type=DataSource");
+ p.setProperty("DB.JdbcDriver", "com.mysql.jdbc.Driver");
+ p.setProperty("DB,JdbcUrl", "jdbc:mysql://localhost/test");
+ p.setProperty("DB.UserName", "test");
+ p.setProperty("DB.Password", "password");
- }
+The `<Resource>` tag has a number of attributes which control the way that the resource get created.
-Can be defined in `tomee.xml` using the following configuration (note the `class-name` attribute):
+* type
- <tomee>
- <Resource id="greet" class-name="org.superbiz.Greeter" />
- </tomee>
-
-This resource must be available in TomEE's system classpath - i.e. it must be defined in a .jar within the `lib/` directory.
+A type that TomEE know. The type is associated with a provider that knows how to create that type, and also any default properties that the resource should have if they are not specified in the resource definition. See <a href="https://github.com/apache/tomee/blob/tomee-1.7.x/tomee/tomee-webapp/src/main/resources/META-INF/org.apache.tomee/service-jar.xml">service-jar.xml</a> for an example of set of service providers that come with TomEE.
-# Application resources
+* provider
-Resources can also be defined within an application, and optionally use classes from the application's classpath. To do define resources in a .war file, include a `WEB-INF/resources.xml`. For an ejb-jar module, use `META-INF/resources.xml`.
+Explicitly specifies a provider to create the resource, using defaults for any properties not specified.
-The format of `resources.xml` is the same in either case. Notice that the root element of the XML is `<resources>` and not `<tomee>`.
+* class-name
- <resources>
- <Resource id="MyResource" class-name="org.superbiz.MyClass"/>
- </resources>
-
-This mechanism allows you to package your custom resources within your application, alongside your application code, rather than requiring a .jar file in the `lib/` directory.
+The fully qualified class that creates the resource. This might the resource class itself, which is created by calling the constructor, or a factory class that provides a specific factory method to create the resource.
-# Field and properties
+* factory-name
-Within a `<Resource>` a number of properties can be specified. Where possible, TomEE will attempt to take these values and set the relevant fields on your resource. In the following example, TomEE will attempt to set the value of the `userName` field on `MyClass` to `tomee`.
+The name of the method to call to create the resource. If this is not specified, the constructor for the class specified by class-name will be used.
- public class MyClass {
+* constructor
+
+Specifies a comma separated list of constructor arguments. These can be other services, or attributes on the resource itself.
- private String userName;
-
- public String getUserName() {
- return userName;
- }
-
- public void setUserName(final String userName) {
- this.userName = userName;
- }
+# Custom resources
+
+TomEE allows you to define resources using your own Java classes, and these can also be injected into managed components in the same way as known resource types are.
+
+So the following simple resource
+
+ public class Configuration {
+ private String url;
+ private String username;
+ private int poolSize;
+
+ // getters and setters
}
- <resources>
- <Resource id="MyResource" class-name="org.superbiz.MyClass">
- UserName tomee
- </Resource>
- </resources>
+Can be defined in `tomee.xml` using the following configuration (note the `class-name` attribute):
+
+ <Resource id="config" class-name="org.superbiz.Configuration">
+ url http://localhost
+ username tomee
+ poolSize 20
+ </Resource>
+
+This resource must be available in TomEE's system classpath - i.e. it must be defined in a .jar within the `lib/` directory.
-You can also add a properties field as shown below, and this will have any used properties from the resource configuration set on it. So as an alternative to the above code, you could do:
+# Field and properties
- public class MyClass {
+As shown above, a resource class can define a number of fields, and TomEE will attempt to apply the values from the resource definition onto those fields.
+
+As an alternative to this, you can also add a properties field as shown below, and this will have any used properties from the resource configuration set added to it. So as an alternative to the above code, you could do:
+
+ public class Configuration {
private Properties properties;
@@ -98,13 +120,33 @@ You can also add a properties field as s
}
+Using the same resource definition:
+
+ <Resource id="config" class-name="org.superbiz.Configuration">
+ url http://localhost
+ username tomee
+ poolSize 20
+ </Resource>
+
+the url, username and poolSize values will now be available in the properties field, so for example, the username property could be accessed via properties.getProperty("username");
+
+# Application resources
+
+Resources can also be defined within an application, and optionally use classes from the application's classpath. To define resources in a .war file, include a `WEB-INF/resources.xml`. For an ejb-jar module, use `META-INF/resources.xml`.
+
+The format of `resources.xml` uses the same `<Resource>` tag as `tomee.xml`. One key difference is the root element of the XML is `<resources>` and not `<tomee>`.
+
<resources>
- <Resource id="MyResource" type="org.superbiz.MyClass">
- UserName tomee
+ <Resource id="config" class-name="org.superbiz.Configuration">
+ url http://localhost
+ username tomee
+ poolSize 20
</Resource>
</resources>
+
+This mechanism allows you to package your custom resources within your application, alongside your application code, rather than requiring a .jar file in the `lib/` directory.
-and reference the UserName properties via `MyClass.getProperties().getProperty("UserName");`. This can also be used with factory create() methods (see below).
+Application resources are bound in JNDI under openejb:Resource/<appname>/<resource id>.
# Additional resource properties
@@ -112,17 +154,35 @@ Resources are typically discovered, crea
The following properties can be used to change this behavior.
-| Property | Values | Description |
-| -------------------------- | ---------------- | -------------|
-| Lazy | true/false | Creates a proxy that defers the actual instantiation of the resource until the first time it is looked up from JNDI. |
-| UseAppClassLoader | true/false | Forces a lazily instantiated resource to use the application classloader, instead of the classloader available when the resources were first processed. |
-| InitializeAfterDeployment | true/false | Forces a resource created with the Lazy property to be instantiated once the application has started, as opposed to waiting for it to be looked up. |
+* Lazy
+
+This is a boolean value, which when true, creates a proxy that defers the actual instantiation of the resource until the first time it is looked up from JNDI. This can be useful if the resource's classpath until the application is started (see below), or to improve startup time by not fully initializing resources that might not be used.
+
+* UseAppClassLoader
+
+This boolean value forces a lazily instantiated resource to use the application classloader, instead of the classloader available when the resources were first processed.
+
+* InitializeAfterDeployment
-By default, if TomEE encounters a custom application resource that cannot be instantiated until the application has started, it will set these three flags to `true`, unless the `Lazy` flag has been explicitly set.
+This boolean setting forces a resource created with the Lazy property to be instantiated once the application has started, as opposed to waiting for it to be looked up. Use this flag if you require the resource to be loaded, irrespective of whether it is injected into a managed component or manually looked up.
-# create() method
+By default, all of these settings are `false`, unless TomEE encounters a custom application resource that cannot be instantiated until the application has started. In this case, it will set these three flags to `true`, unless the `Lazy` flag has been explicitly set.
-In some circumstances, it may be desirable to add some additional logic to the creation process, or to use a factory pattern to create resources. TomEE also provides this facility via the `create` method. The `factory-name` attribute on the resource can reference any no argument method that returns an object on the class specified in the `class-name` attribute.
+# Initializing resources
+
+## constructor
+
+By default, if no factory-name attribute and no constructor attribute is specified on the `Resource`, TomEE will instantiate the resource using its no-arg constructor. If you wish to pass constructor arguments, specify the arguments as a comma separated list:
+
+ <Resource id="config" class-name="org.superbiz.Configuration" constructor="id, poolSize">
+ url http://localhost
+ username tomee
+ poolSize 20
+ </Resource>
+
+## factory-name method
+
+In some circumstances, it may be desirable to add some additional logic to the creation process, or to use a factory pattern to create resources. TomEE also provides this facility via the `factory-name` method. The `factory-name` attribute on the resource can reference any no argument method that returns an object on the class specified in the `class-name` attribute.
For example:
@@ -154,9 +214,9 @@ For example:
</Resource>
</resources>
-# @PostConstruct / @PreDestroy
+## @PostConstruct / @PreDestroy
-As an alternative to using a factory method, you can use @PostConstruct and @PreDestroy methods within your resource class (note that you cannot use this within a factory class) to manage any additional creation or cleanup activities. TomEE will automatically call these methods when the application is started and destroyed. Using @PostConstruct will effectively force a lazily loaded resource to be instantiated when the application is starting - in the same way that the `InitializeAfterDeployment` property does.
+As an alternative to using a factory method or a constructor, you can use @PostConstruct and @PreDestroy methods within your resource class (note that you cannot use this within a different factory class) to manage any additional creation or cleanup activities. TomEE will automatically call these methods when the application is started and destroyed. Using @PostConstruct will effectively force a lazily loaded resource to be instantiated when the application is starting - in the same way that the `InitializeAfterDeployment` property does.
public class MyClass {
@@ -178,8 +238,6 @@ As an alternative to using a factory met
}
-
-
# Examples
The following examples demonstrate including custom resources within your application: