1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<?xml version="1.0" encoding="utf-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<chapter id="How-to-Use-JNDI">
<title>
How to Use JNDI
</title>
<section role="h2" id="HowtoUseJNDI-HowtousethePropertiesFileInitialContextFactory">
<title>
How to use the PropertiesFileInitialContextFactory
</title>
<para>
This ContextFactory uses a java properties formatted file to
setup initial values.
</para>
<section role="h3" id="HowtoUseJNDI-JNDIPropertysetup">
<title>
JNDI Property setup
</title>
<para>
By setting the JNDI Initial Context Factory and URL as
below it is possible to load any File from the locally
mounted file system to use for JNDI purposes. The format
of the file is described in the next section.
</para>
<programlisting>
java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
java.naming.provider.url = <path to JNDI File>
</programlisting>
<para>
By simply setting these two system properties you can jump
straight to the InitialContext creation in your code.
</para>
</section>
<section role="h3" id="HowtoUseJNDI-Examplepropertiesfile">
<title>
Example properties file </title>
<para>
This is the example properties file.
</para>
<programlisting>
# register some connection factories
# connectionfactory.[jndiname] = [ConnectionURL]
connectionfactory.local = amqp://guest:guest@clientid/testpath?brokerlist='vm://:1'
# register some queues in JNDI using the form
# queue.[jndiName] = [physicalName]
queue.MyQueue = example.MyQueue
# register some topics in JNDI using the form
# topic.[jndiName] = [physicalName]
topic.ibmStocks = stocks.nyse.ibm
# Register an AMQP destination in JNDI
# NOTE: Qpid currently only supports direct,topics and headers
# destination.[jniName] = [BindingURL]
destination.direct = direct://amq.direct//directQueue
</programlisting>
<para>
The property file allows a number of queues to be defined that
can then be discovered via JNDI. There are four properties used
by the PFICFactory.
<emphasis>connectionfactory.<jndiname></emphasis> this is the <xref linkend="Connection-URL-Format"/> that the connection
factory will use to perform connections.
<emphasis>queue.<jndiname></emphasis> this defines a jms queue or in
amqp a amq.direct exchange
<emphasis>topic.<jndiname></emphasis> this defines a jms topic or in
amqp a amq.topic exchange
<emphasis>destination.<jndiname></emphasis> this takes a <xref linkend="BindingURLFormat"/>
and so can be used for defining all amq destinations, queues,
topics and header matching.
</para><para>
In all of these properties the <emphasis><jndiname></emphasis> is the
string value that would be given when performing a lookup.
</para><para>
<emphasis>NOTE</emphasis>: This does not create the queue on the broker. You
should ensure that you have created the queue before publishing
to it. Queues can be declared in the virtualhosts.xml file so
that they are created on broker startup, or created dynamically
by consuming clients. Topics and other destinations that use
temporary queues cannot be created in this way, so a consumer
must be created first before publishing messages with mandatory
routing.
</para>
</section>
<section role="h3" id="HowtoUseJNDI-Examplelookupcode">
<title>
Example lookup code
</title><!--h3-->
<para>
The <emphasis>bindingValue</emphasis> is the String that would be placed in
<emphasis><jndiname></emphasis> above.
</para>
<example>
<title>Simple JNDI lookup using files</title>
<programlisting>
//Ensure you have your system properties set
final String INITIAL_CONTEXT_FACTORY = "org.apache.qpid.jndi.PropertiesFileInitialContextFactory";
System.setProperty(Context.INITIAL_CONTEXT_FACTORY, INITIAL_CONTEXT_FACTORY);
System.setProperty(Context.PROVIDER_URL, _JNDIFile);
// Create the initial context
Context ctx = new InitialContext();
// Perform the binds
object = ctx.lookup(bindingValue);
// Close the context when we're done
ctx.close();
</programlisting>
</example>
<example>
<title>Simple JNDI lookup using properties</title>
<programlisting>
final String INITIAL_CONTEXT_FACTORY = "org.apache.qpid.jndi.PropertiesFileInitialContextFactory";
final String CONNECTION_JNDI_NAME = "local";
final String CONNECTION_NAME = "amqp://guest:guest@clientid/testpath?brokerlist='vm://:1'";
final String QUEUE_JNDI_NAME = "queue";
final String QUEUE_NAME = "example.MyQueue";
// Set the properties ...
Properties properties = new Properties();
properties.put(Context.INITIAL_CONTEXT_FACTORY, INITIAL_CONTEXT_FACTORY);
properties.put("connectionfactory."+CONNECTION_JNDI_NAME , CONNECTION_NAME);
properties.put("queue."+QUEUE_JNDI_NAME , QUEUE_NAME);
// Create the initial context
Context ctx = new InitialContext(properties);
// Perform the lookups
ConnectionFactory factory = (ConnectionFactory)ctx.lookup(CONNECTION_JNDI_NAME);
Queue queue = (Queue)ctx.lookup(QUEUE_JNDI_NAME);
// Close the context when we're done
ctx.close();
</programlisting>
</example>
</section>
<section>
<title>Using Qpid with Other JNDI Providers</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Using Qpid with other JNDI Providers.xml"/>
</section>
<!--h2-->
</section>
</chapter>
|
