Google Git
Sign in
apache / tomee-site-pub / 43cf80e624a0cecf0f38bef5ef2614bfb2410f57 / . / tomee-9.0 / docs / application-resources.html
blob: 2fc6ccd269adb6f05ab7ec6019aa6639e1184ab1 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Apache TomEE</title>
<meta name="description"
content="Apache TomEE is a lightweight, yet powerful, JavaEE Application server with feature rich tooling." />
<meta name="keywords" content="tomee,asf,apache,javaee,jee,shade,embedded,test,junit,applicationcomposer,maven,arquillian" />
<meta name="author" content="Luka Cvetinovic for Codrops" />
<link rel="icon" href="../../favicon.ico">
<link rel="icon" type="image/png" href="../../favicon.png">
<meta name="msapplication-TileColor" content="#80287a">
<meta name="theme-color" content="#80287a">
<link rel="stylesheet" type="text/css" href="../../css/normalize.css">
<link rel="stylesheet" type="text/css" href="../../css/bootstrap.css">
<link rel="stylesheet" type="text/css" href="../../css/owl.css">
<link rel="stylesheet" type="text/css" href="../../css/animate.css">
<link rel="stylesheet" type="text/css" href="../../fonts/font-awesome-4.1.0/css/font-awesome.min.css">
<link rel="stylesheet" type="text/css" href="../../fonts/eleganticons/et-icons.css">
<link rel="stylesheet" type="text/css" href="../../css/jqtree.css">
<link rel="stylesheet" type="text/css" href="../../css/idea.css">
<link rel="stylesheet" type="text/css" href="../../css/cardio.css">
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-2717626-1']);
_gaq.push(['_setDomainName', 'apache.org']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="preloader">
<img src="../../img/loader.gif" alt="Preloader image">
</div>
<nav class="navbar">
<div class="container">
<div class="row"> <div class="col-md-12">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/">
<span>
<img src="../../img/logo-active.png">
</span>
Apache TomEE
</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right main-nav">
<li><a href="../../docs.html">Documentation</a></li>
<li><a href="../../community/index.html">Community</a></li>
<li><a href="../../security/security.html">Security</a></li>
<li><a href="../../download-ng.html">Downloads</a></li>
</ul>
</div>
<!-- /.navbar-collapse -->
</div></div>
</div>
<!-- /.container-fluid -->
</nav>
<div id="main-block" class="container main-block">
<div class="row title">
<div class="col-md-12">
<div class='page-header'>
<h1>Application Resources</h1>
</div>
</div>
</div>
<div class="row">
<div class="col-md-12">
<div class="sect1">
<h2 id="_resources">Resources</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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 <code>tomee.xml</code>
configuration file, a <code>resources.xml</code> file within an application, or as
a system property. Defining a resource in <code>tomee.xml</code> will make it
available server-wide, whereas defining the resource within a
<code>resources.xml</code> file makes it available to a specific application.</p>
</div>
<div class="paragraph">
<p>As a simple example, a JMS queue can be defined within <code>tomee.xml</code> with
the following configuration.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;tomee&gt;
&lt;Resource id="MyQueue" type="jakarta.jms.Queue"/&gt;
&lt;/tomee&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>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 <code>@Resource</code> annotation, as shown
below. The <code>name</code> attribute on the <code>@Resource</code> annotation should match
the <code>id</code> attribute on the <code>Resource</code> tag.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">public class JmsClient {
@Resource(name="MyQueue")
private Queue queue;
public void sendMessage() {
// implementation here...
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>As an alternative to defining a resource in XML, resources can also be
defined using system properties:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties">MyQueue = new://Resource?type=jakarta.jms.Queue</code></pre>
</div>
</div>
<div class="paragraph">
<p>Resources, or attributes for resources specified using system properties
will override definitions specified in <code>tomee.xml</code>. Server-wide
resources can be looked up in JNDI under the following name:
openejb:Resources/resource id.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_defining_resources">Defining Resources</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>&lt;Resource&gt;</code> 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 <code>Resource</code> tag.</p>
</div>
<div class="paragraph">
<p>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 <code>&lt;Resource&gt;</code> tag.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Resource id="DB" type="DataSource"&gt;
JdbcDriver com.mysql.jdbc.Driver
JdbcUrl jdbc:mysql://localhost/test
UserName test
Password password
&lt;/Resource&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>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: <code>&lt;resourceId&gt;.&lt;propertyName&gt;=&lt;value&gt;</code>. The
system properties equivalent of the resource above is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">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");</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>&lt;Resource&gt;</code> tag has a number of attributes which control the way
that the resource get created.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>type</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>A type that TomEE knows. 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 service-jar.xml for an example set of service providers
that come with TomEE.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>provider</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Explicitly specifies a provider to create the resource, using defaults
for any properties not specified.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>class-name</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>factory-name</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>constructor</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Specifies a comma separated list of constructor arguments. These can be
other services, or attributes on the resource itself.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_custom_resources">Custom resources</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>So the following simple resource</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">public class Configuration {
private String url;
private String username;
private int poolSize;
// getters and setters
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Can be defined in <code>tomee.xml</code> using the following configuration (note
the <code>class-name</code> attribute):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Resource id="config" class-name="org.superbiz.Configuration"&gt;
url http://localhost
username tomee
poolSize 20
&lt;/Resource&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This resource must be available in TomEE&#8217;s system classpath - i.e. it
must be defined in a .jar within the <code>lib/</code> directory.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_field_and_properties">Field and properties</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">public class Configuration {
private Properties properties;
public Properties getProperties() {
return properties;
}
public void setProperties(final Properties properties) {
this.properties = properties;
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Using the same resource definition:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Resource id="config" class-name="org.superbiz.Configuration"&gt;
url http://localhost
username tomee
poolSize 20
&lt;/Resource&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>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");</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_application_resources">Application resources</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Resources can also be defined within an application, and optionally use
classes from the application&#8217;s classpath. To define resources in a .war
file, include a <code>WEB-INF/resources.xml</code>. For an ejb-jar module, use
<code>META-INF/resources.xml</code>.</p>
</div>
<div class="paragraph">
<p>The format of <code>resources.xml</code> uses the same <code>&lt;Resource&gt;</code> tag as
<code>tomee.xml</code>. One key difference is the root element of the XML is
<code>&lt;resources&gt;</code> and not <code>&lt;tomee&gt;</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;resources&gt;
&lt;Resource id="config" class-name="org.superbiz.Configuration"&gt;
url http://localhost
username tomee
poolSize 20
&lt;/Resource&gt;
&lt;/resources&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This mechanism allows you to package your custom resources within your
application, alongside your application code, rather than requiring a
.jar file in the <code>lib/</code> directory.</p>
</div>
<div class="paragraph">
<p>Application resources are bound in JNDI under
openejb:Resource/appname/resource id.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_additional_resource_properties">Additional resource properties</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Resources are typically discovered, created, and bound to JNDI very
early on in the deployment process, as other components depend on them.
This may lead to problems where the final classpath for the application
has not yet been determined, and therefore TomEE is unable to load your
custom resource.</p>
</div>
<div class="paragraph">
<p>The following properties can be used to change this behavior.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Lazy</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>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&#8217;s classpath
until the application is started (see below), or to improve startup time
by not fully initializing resources that might not be used.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>UseAppClassLoader</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This boolean value forces a lazily instantiated resource to use the
application classloader, instead of the classloader available when the
resources were first processed.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>InitializeAfterDeployment</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>By default, all of these settings are <code>false</code>, 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
<code>true</code>, unless the <code>Lazy</code> flag has been explicitly set.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_initializing_resources">Initializing resources</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_constructor">constructor</h3>
<div class="paragraph">
<p>By default, if no factory-name attribute and no constructor attribute is
specified on the <code>Resource</code>, 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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Resource id="config" class-name="org.superbiz.Configuration" constructor="id, poolSize"&gt;
url http://localhost
username tomee
poolSize 20
&lt;/Resource&gt;</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_factory_name_method">factory-name method</h3>
<div class="paragraph">
<p>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 <code>factory-name</code>
method. The <code>factory-name</code> attribute on the resource can reference any
no argument method that returns an object on the class specified in the
<code>class-name</code> attribute.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">public class Factory {
private Properties properties;
public Object create() {
MyResource resource = new MyResource();
// some custom logic here, maybe using this.properties
return resource;
}
public Properties getProperties() {
return properties;
}
public void setProperties(final Properties properties) {
this.properties = properties;
}
}
&lt;resources&gt;
&lt;Resource id="MyResource" class-name="org.superbiz.Factory" factory-name="create"&gt;
UserName tomee
&lt;/Resource&gt;
&lt;/resources&gt;</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="__postconstruct_predestroy">@PostConstruct / @PreDestroy</h3>
<div class="paragraph">
<p>As an alternative to using a factory method or a constructor, you can
use <code>@PostConstruct</code> and <code>@PreDestroy</code> 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 <code>@PostConstruct</code> will effectively force a lazily loaded
resource to be instantiated when the application is starting - in the
same way that the <code>InitializeAfterDeployment</code> property does.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">public class MyClass {
private Properties properties;
public Properties getProperties() {
return properties;
}
public void setProperties(final Properties properties) {
this.properties = properties;
}
@PostConstruct
public void postConstruct() throws MBeanRegistrationException {
// some custom initialization
}
}
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_examples">Examples</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The following examples demonstrate including custom resources within
your application:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>resources-jmx-example</p>
</li>
<li>
<p>resources-declared-in-webapp</p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-sm-6 text-center-mobile">
<h3 class="white">Be simple. Be certified. Be Tomcat.</h3>
<h5 class="light regular light-white">"A good application in a good server"</h5>
<ul class="social-footer">
<li><a href="https://www.facebook.com/ApacheTomEE/"><i class="fa fa-facebook"></i></a></li>
<li><a href="https://twitter.com/apachetomee"><i class="fa fa-twitter"></i></a></li>
<li><a href="https://plus.google.com/communities/105208241852045684449"><i class="fa fa-google-plus"></i></a></li>
</ul>
</div>
<div class="col-sm-6 text-center-mobile">
<div class="row opening-hours">
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../latest/docs/" class="white">Documentation</a></h5>
<ul class="list-unstyled">
<li><a href="../../latest/docs/admin/configuration/index.html" class="regular light-white">How to configure</a></li>
<li><a href="../../latest/docs/admin/file-layout.html" class="regular light-white">Dir. Structure</a></li>
<li><a href="../../latest/docs/developer/testing/index.html" class="regular light-white">Testing</a></li>
<li><a href="../../latest/docs/admin/cluster/index.html" class="regular light-white">Clustering</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../latest/examples/" class="white">Examples</a></h5>
<ul class="list-unstyled">
<li><a href="../../latest/examples/simple-cdi-interceptor.html" class="regular light-white">CDI Interceptor</a></li>
<li><a href="../../latest/examples/rest-cdi.html" class="regular light-white">REST with CDI</a></li>
<li><a href="../../latest/examples/ejb-examples.html" class="regular light-white">EJB</a></li>
<li><a href="../../latest/examples/jsf-managedBean-and-ejb.html" class="regular light-white">JSF</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../community/index.html" class="white">Community</a></h5>
<ul class="list-unstyled">
<li><a href="../../community/contributors.html" class="regular light-white">Contributors</a></li>
<li><a href="../../community/social.html" class="regular light-white">Social</a></li>
<li><a href="../../community/sources.html" class="regular light-white">Sources</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../security/index.html" class="white">Security</a></h5>
<ul class="list-unstyled">
<li><a href="http://apache.org/security" target="_blank" class="regular light-white">Apache Security</a></li>
<li><a href="http://apache.org/security/projects.html" target="_blank" class="regular light-white">Security Projects</a></li>
<li><a href="http://cve.mitre.org" target="_blank" class="regular light-white">CVE</a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="row bottom-footer text-center-mobile">
<div class="col-sm-12 light-white">
<p>Copyright &copy; 1999-2016 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
</div>
</div>
</div>
</footer>
<!-- Holder for mobile navigation -->
<div class="mobile-nav">
<ul>
<li><a hef="../../latest/docs/admin/index.html">Administrators</a>
<li><a hef="../../latest/docs/developer/index.html">Developers</a>
<li><a hef="../../latest/docs/advanced/index.html">Advanced</a>
<li><a hef="../../community/index.html">Community</a>
</ul>
<a href="#" class="close-link"><i class="arrow_up"></i></a>
</div>
<!-- Scripts -->
<script src="../../js/jquery-1.11.1.min.js"></script>
<script src="../../js/owl.carousel.min.js"></script>
<script src="../../js/bootstrap.min.js"></script>
<script src="../../js/wow.min.js"></script>
<script src="../../js/typewriter.js"></script>
<script src="../../js/jquery.onepagenav.js"></script>
<script src="../../js/tree.jquery.js"></script>
<script src="../../js/highlight.pack.js"></script>
<script src="../../js/main.js"></script>
</body>
</html>