View File | Revision Log | Show Annotations | Download File | View Changeset
/hippo/experimental/hippo-jmstestapp/trunk/README.txt
Revision: 7273
Committed: Thu Jul 19 00:34:51 2007 UTC (15 years, 4 months ago) by bvanhalderen
Content type: text/plain
File size: 13004 byte(s)
Log Message:
SMALS-20: update jms settings for WebLogic

File Contents

# Content
1 Copyright 2001-2007 Hippo (www.hippo.nl)
2
3 Licensed under the Apache License, Version 2.0 (the "License");
4 you may not use this file except in compliance with the License.
5 You may obtain a copy of the License at
6
7 http://www.apache.org/licenses/LICENSE-2.0
8
9 Unless required by applicable law or agreed to in writing, software
10 distributed under the License is distributed on an "AS IS" BASIS,
11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 See the License for the specific language governing permissions and
13 limitations under the License.
14
15
16 HIPPO JMS DEMONSTRATION, SAMPLE AND UTILITY PROGRAM
17 ===
18
19 This tree contains a testing application and a utility to find out if the JMS
20 messaging from the Hippo repository works correctly.
21
22
23 SETUP
24
25 The test application is contained witin the directory sample, while the other
26 files relate to building and the utility application. After building you will
27 end up with two WAR files, which can be deployed seperately or next to each
28 other. The test-application requires a working Hippo repository to be
29 present, the utility application does not require one, but is only limited in
30 functionality when there isn't a repository present. Therefor we assume that
31 there is a fully functional Hippo repository present, which has also been
32 properly initialized with the hippo-repository-initialize tool! (see repository
33 documentation).
34
35 Before building you need to set a number of parameters which instruct the
36 application to the right location of the hippo repository and the JMS
37 connections. This requires modification of the following files:
38
39 sample/build.properties (copy the build.properties-sample for a sample)
40 sample/src/config/jms-connection.xconf
41 sample/src/config/resource-ref-topicconnectionfactory.xweb
42 sample/src/config/resource-env-ref-topic.xweb
43 src/main/resources/repository.properties
44 src/main/resources/jndi.properties
45 src/main/webapp/WEB-INF/web.xml
46 src/main/webapp/WEB-INF/weblogic.xml
47
48 The default settings are to use a Hippo repository running on:
49 http://localhost:7001/repository/
50 Note that setting differs from a default installation of the Hippo repository
51 where the repository runs on the context-root "/" instead of "/repository/".
52 This allows the test application (which requires to be run on the context-root
53 of "/"), repository and utility program to all run within the same instance of
54 WebLogic.
55
56 The JMS related default settings are to use the embedded application container
57 (WebLogic) JMS system with as topic connection factory the JNDI name
58 "jms/repositoryTCF" and as topic "jms/repositoryTopic". Within WebLogic they
59 will map (through weblogic.xml) to the internal names "jms.repositoryTCF" and
60 "jms.repositoryTopic" respectively and to use the default initial context and
61 JNDI providers (i.e. they are not explicitly specified, so picked up from the
62 system defaults).
63
64
65 CONFIGURATION
66
67 To make modifications edit the files above as follows:
68
69 sample/build.properties:
70
71 Within this file you can specify a number of parameters which direct the
72 Cocoon application to the right repository and JMS system. This
73 build.properties file is set up as usual with any Hippo-Cocoon site and
74 further documentation on the build properties can be found on the Wiki of
75 Hippo.
76
77 Set the properties starting with maven.cocoon.repository. to the right
78 location of your hippo repository, where the path by appending the
79 following:
80 "http://"
81 property maven.cocoon.repository.host
82 ":"
83 property maven.cocoon.repository.port
84 property maven.cocoon.repository.rootpath
85 property /files/default.preview
86 "/content"
87 end up into a valid URL to the repository content.
88
89 Leave jms.jndi.initial-factory and jms.jndi.provider blank to use the default,
90 embedded JMS and JNDI, otherwise specify them here.
91 sample/src/config/jms-connection.xconf).
92 For weblogic, the jms.jndi.inital-factory defaults to
93 weblogic.jndi.WLInitialContextFactory.
94 If you want to explicitly specify jms.jndi.initial-factory or
95 jms.jndi.provider then you will have to alter
96 sample/src/config/jms-connection.xconf too to pick up the explicit value.
97
98 Set jms.connection-factory and jms.topic to the right JMS topic connection
99 factory and JMS topic.
100
101 sample/src/config/jms-connection.xconf
102
103 If you want to specificy an explicit initial factory (i.e. having specified
104 a non-blank jms.jndi.initial-factory property in your build.properties) then
105 you need to comment in the parameter java.naming.factory.initial currently
106 commented out using <!-- -->. Then java.naming.factory.secondary is only
107 used when specifying an initial context named
108 "nl.hippo.jmsbridge.BridgeContextFactory" (discused elsewhere).
109
110 sample/src/config/resource-env-ref-topic.xweb
111 sample/src/config/resource-env-ref-topic.xweb
112
113 The setting in these file ends up in the WEB-INF/web.xml which declare which
114 JNDI names are looked up by the application and should correspond to the
115 jms.connection-factory and jms.topic properties in the build.properties
116 file.
117
118 src/main/resources/repository.properties
119
120 Like the sample/build.properties, the location of the repository is
121 specified here as a concatenation of the following elements:
122 "http://"
123 property hippo.client.host
124 ":"
125 property hippo.client.port
126 "/"
127 property hippo.client.contextroot
128 property hippo.client.filespath
129 "default.preview/content"
130 Furthermore the hippo.client.namespace property should correspond to the
131 namespace in use at the repository (which is normally "default"), and the
132 hippo.client.username, hippo.client.password and hippo.client.realm identify
133 the right authorization credentials to gain write access to the repository
134 location.
135
136 Note that because the repository is assumed to run in an application
137 container, the hippo.client.namespace is not used to form the URL to the
138 repository, but hippo.client.contextroot is. For non-application container
139 based hippo-repository, the hippo.client.contextroot should not be
140 specified, at which time the hippo.client.namespace is automatically used.
141
142 src/main/resources/jndi.properties
143
144 Like in the sample/build.properties, you can specifiy the JMS repository
145 topic connection factory and topic to be used by the utility program.
146
147 The java.naming.factory.initial property served the same purpose as the
148 jms.jndi.initial-factory from the sample/build.properties and can be left
149 blank to indicate the default to be used. The java.naming.factory.secondary
150 and java.naming.factory.bindings are used only when java.naming.factory.initial
151 is set to nl.hippo.jmsbridge.BridgeContextFactory. The
152 hippo.client.jms.factory and hippo.client.jms.topic correspond to the
153 jms.connection-factory and jms.topic of the sample/build.properties.
154
155 src/main/webapp/WEB-INF/web.xml
156
157 If you have changed the names of the JMS topic connection factory or the JMS
158 topic from jms/repositoryTCF and jms/repositoryTopic then you need to change
159 the two resource-ref sections in this file also to the proper names.
160
161 src/main/webapp/WEB-INF/weblogic.xml
162
163 This file is specific to WebLogic and specifies, amongst others, how the
164 JNDI names are mapped to the physical name in WebLogic. Current if you
165 change the name jms/repositoryTCF or jms/repositoryTopic then you need to
166 adapt also this file. Also if you physical address of these two JNDI names
167 is not jms.repositoryTCF and jms.repositoryTopic then you need to modify
168 this file.
169
170
171 COMPILE AND BUILD
172
173 This project is dependent on a few yet-unreleased packages. Please copy the
174 jar files that can be found in the dependencies directory to your local maven
175 repository, under a unix-like environment this would be accomplished using:
176
177 mkdir -p $HOME/.maven/repository/hippo/jars
178 cp dependencies/*.jar $HOME/.maven/repository/hippo/jars/.
179
180 Having checked all the parameters above, you can proceed building the test
181 application and utility program. You can compile with either maven 1 or maven
182 2.0.6 (or better) with a JDK 1.4 installation. With maven 1 run:
183 maven war
184 to compile the utility program and change directory to the sample application
185 and compile with the cocoon WAR target:
186 cd sample
187 maven cocoon:war
188 Using maven 2 you can only compile the utility program by simply typing:
189 mvn
190
191
192 INSTALLING
193
194 The sample application and the utility application are build as seperate WAR
195 files. The sample application must be installed on the root context "/" of a
196 virtual host in you web application container. The utility test application
197 can be installed on any context. We suggest to use "/test". Furthermore the
198 earlier settings all refered to the installation on "localhost" and the
199 repository in the context root "/repository" on localhost. Deploy both WAR
200 files within these context paths on your (WebLogic) application container.
201
202
203 RUNNING AND USAGE
204
205 The sample application:
206
207 The sample application is a simple browser to the repository. It displays (on
208 the left hand side) a flattened listing of the documents contained in the
209 repository at a compiled in location. When one of the documents is selected,
210 it displays the content of the document in main part of the screen. It caches
211 the content of the document and listenes (through JMS) for any updates on the
212 documents to occur.
213
214 If a document is updated at the repository, then the application is instructed
215 to purge its cached document and if (and not otherwise!) the page is reloaded
216 it will display the modified document.
217
218 With this sample application you can check whether the JMS is functionally
219 properly. You can see a small delay between a document change on the
220 repository, and before the sample application will display the modified
221 document.
222
223 The utility application:
224
225 This application is in fact a set of individual servlets which can be
226 retrieved seperately though a main index page.
227
228 main page (accessible at http://localhost:7001/test/index.html):
229
230 The left part of the webpage shows links to the other servlets and the
231 main part of the page shows the document testing.xml at the repository
232 location indicated at compile time. At any time, clicking the logo of
233 hippo shows this main page and the re-fetched document from the
234 repository.
235
236 updater:
237
238 This servlet constantly runs in the background and uploads every 3 seconds
239 a new version of the document testing.xml at the specified repository
240 location. When accessing this servlet through the main page it will show
241 how often the document has been updated. The content of the document also
242 indicates the current update count.
243
244 listener:
245 low-level listener:
246
247 These two listeners perform the same type of operation, but one uses a
248 low-level listener while the other uses the hippo-repository java adapter.
249
250 Both constantly listen at the repository JMS connection whether the
251 document testing.xml has been updated. They count the number of times
252 they have received such an update, and when the page specific to this
253 servlet is accessed, display the count of the number of updates received.
254
255 low-level updater:
256
257 This updater program explicitly sends updates for the testing.xml document
258 through JMS, without actually updating the content of the document in the
259 repository (it does not access the repository, but sends the JMS event
260 itself).
261
262 By modifying the web.xml, for example by removing the low-level updater you
263 can check whether in fact the JMS messages are in fact generated by the
264 repository rather than the utility program.
265
266 It is also possible to perform manual updates (like the updater servlet
267 action). using the UpdaterProgram java source code. When using maven2 this
268 program can be run using:
269 mvn exec:java
270 and which performs 1000 updates like the updater would perform.
271
272
273 JMSBRIDGE INSTALLATION
274
275 In sample/build.properties, set the jms.jndi.initial-factory property to the
276 following:
277
278 jms.jndi.initial-factory=nl.hippo.jmsbridge.BridgeContextFactory
279
280 In sample/src/config/jms-connection.xconf make sure the parameters
281 java.naming.factory.initial and java.naming.factory.secondary are commented
282 in, and the parameter java.naming.factory.bindings is also added. The patch
283 in this jms-connection.xconf should look somewhat like:
284
285 <topic-connection name="${jms.connection}">
286 <parameter name="java.naming.factory.initial" value="nl.hippo.jmsbridge.BridgeContextFactory"/>
287 <parameter name="java.naming.factory.secondary" value="weblogic.jndi.WLInitialContextFactory"/>
288 <parameter name="java.naming.factory.bindings" value="jms/repositoryTopic jms/repositoryTCF"/>
289 <parameter name="java.naming.factory.options" value="asynchronous-operations=emulate"/>
290 <parameter name="connection-factory" value="jms/repositoryTCF"/>
291 <parameter name="auto-reconnect" value="false"/>
292 </topic-connection>
293
294 Within a WebLogic environment it is vital to use these settings!

Properties

Name Value
svn:eol-style native
svn:keywords Id