Skip to Content
Last modified by Pascal Robert on 2012/07/21 20:39
Hide last authors
Pascal Robert 49.1 1 {{warning}}
George Domurot 51.1 2 This script can be used for WOLips 3.3.x only, the build.xml in WOLips 3.4.x and later already have the split install/embedded stuff built-in.
Pascal Robert 49.1 3 {{/warning}}
4
George Domurot 61.1 5 == WOLips 3.4.x, and later, Side-note ==
6
Pascal Robert 63.1 7 {{warning}}
Pascal Robert 64.1 8 If you are updating an older project, make sure you get the latest build.xml file. Create a new project, then copy/paste the contents of the fresh build.xml file into your project's build.xml file.
Pascal Robert 63.1 9 {{/warning}}
10
Pascal Robert 64.1 11 For WOLips 3.4.x and later, while embedding is built-in, it's not enabled by default. To enable embedding:
George Domurot 61.1 12
13 * make sure you are in the WO Explorer view
14 * right-click your project folder, select Properties, select WOLips Deployment
15 * check the related, if not all, options under Embed Frameworks
16
17 To create a versioned/dated bundle of your app and resources:
18
19 * make sure you are in the Navigator view
20 * edit build.properties, and add:
Pascal Robert 64.1 21 * {{code language="none"}}build.app.name=MyApp-2009-07-14{{/code}}
George Domurot 61.1 22
Pascal Robert 64.1 23 There is a known bug with WO 5.4.x (for those not using the latest Wonder release) regarding proper linking to your web server resources within the embedded frameworks. The WOFrameworksBaseURL isn't set correctly. To do this you'll need to programmatically set this within your Application constructor:
George Domurot 61.1 24
Pascal Robert 64.1 25 * {{code language="none"}}setFrameworksBaseURL("/WebObjects/MyApp-2009-07-14.woa/Frameworks");{{/code}}
George Domurot 61.1 26
27 Within build.properties (I may need to be corrected on this), the best approach to linking your embedded framework's web server resources automatically is to include (however the bug noted above breaks this):
28
Pascal Robert 64.1 29 * {{code language="none"}}frameworksBaseURL=/WebObjects/${build.app.name}.woa/Frameworks{{/code}}
George Domurot 61.1 30
George Domurot 21.1 31 == Introduction ==
32
Pascal Robert 64.1 33 The previous tutorial articles provide details of customization of the default ant build script that is present in your WebObjects projects. This article provides a fully custom build script that you can just drop into your project and use it as an alternative to the default build.xml. This script is called the "split_embedded_build" script. Along with providing the script, this article explains in detail what deployment artifacts are produced by the build. Hopefully the functionality in this script will make their way into the standard script someday with configuration parameters settable in a simple way in the build.properties file.
George Domurot 21.1 34
35 == Pre-requisites ==
36
Pascal Robert 64.1 37 This [[script>>attach:split_embedded_build.xml]] only works with the modern WOLips project format and the WOnderApplication project template format (since the layout of regular projects is now similar to Wonder layout). However the script is easily changed to accommodate the "old" standard format by changing the dir names in the script (for example "Sources" in the new project layout was "src" in the old layout)
Kieran Kelleher 37.1 38
39 {{info title="Modern WebObjects Project Layout"}}
40 This layout is the standard layout for all WebObjects projects created by WOLips (rev #4735 at least). The distinct folder names indicate if your project is in this modern format and if yours is the same, then this ant script should work.
41
Pascal Robert 64.1 42 [[image:attach:modern_project_layout.jpg]]
Kieran Kelleher 37.1 43 {{/info}}
44
45 == Installation and Usage of the Script ==
46
Pascal Robert 64.1 47 Have no fear , you will not break anything by dropping this script as is into your project and trying it out. You can just use it as is without replacing your default build.xml
Kieran Kelleher 37.1 48
Pascal Robert 64.1 49 * So, download the [[script>>attach:split_embedded_build.xml]] by right-clicking this [[link>>attach:split_embedded_build.xml]] and selecing Save As... or whatever your browser uses for saving contents at a link destination.
Kieran Kelleher 47.1 50 * Drag it to the root of your project.
Kieran Kelleher 37.1 51
Pascal Robert 64.1 52 * Open the Ant run configuration for the script by right-clicking on the script and selecting the menu shown below.
Kieran Kelleher 37.1 53
54 {{info title="Using the Ant Script"}}
Pascal Robert 64.1 55 [[image:attach:running_the_script.jpg]]
Kieran Kelleher 47.1 56 {{/info}}
Kieran Kelleher 37.1 57
Pascal Robert 64.1 58 * Next select the "clean" and compileAndBuild" tasks. If necessary use the "Order..." button to ensure that "clean" comes before "compileAndBuild".
Kieran Kelleher 47.1 59
60 {{info title="Configure the Ant Tasks to be run"}}
Pascal Robert 64.1 61 [[image:attach:ant_tasks.jpg]]
Kieran Kelleher 37.1 62 {{/info}}
Kieran Kelleher 47.1 63
64 * Click the Run button to run the ant script and your fully embedded split install deployment bundles will be created in the "dist" folder.
65
66 == Customizing Application/Bundle Name ==
67
68 It is common to want to use custom bundle build names. There are a number of advantages to having a unique application name for each build:
69
70 * For example, you might want to have a name that reflects the current revision so that a clean bundle is deployed without overwriting older version bundles on the servers.
71 * If the current and new versions of the app are compatible with the current database schema, smooth zero-downtime "rolling upgrades" are possible by using this strategy... and the ability to switch back to the older version if an unexpected deployment problem occurs
72 * Because we are using fully embedded split bundles, the unique deployment name will ensure that web server resources all get a new URL ensuring that older versions cached by browsers will not be used for new deployed version apps ... which can be important for javascript and image updates for example.
73
74 OK, so getting to the point, an optional custom app name can be set in the project's build.properties file by simply adding a property "build.app.name" as shown below.
75
76 {{info title="Customizing the Application Build Name"}}
Pascal Robert 64.1 77 [[image:attach:custom_app_name.jpg]]
Kieran Kelleher 47.1 78 {{/info}}
79
80 == Features ==
81
82 The desirable features of this script are
83
84 * Fully embedded - your deployed bundle reflects the frameworks you developed and tested with instead of risky assumption that the server has the exact same WebObjects and 3rd party frameworks configuration and versions that you had on your development machine.
85 * Custom application/bundle names - new version has new URLs for webserver resources that are often cached by browser so the new version will be requested since the URL is different.
86 * Self-contained deployment bundles - all required frameworks are embedded - minimal dependency on target server configuration and versions. For example, there is no need to install Wonder frameworks on your deployment server since the ones you developed and tested with are embedded in the deployment bundles. Experience has shown that this improves consistency of deployment reliability.
87 * Compressed gzipped tar archives of both application and webserver bundles are created, ready for copying to target server(s)
88 ** This is easily decompressed on the server using
Pascal Robert 64.1 89 ** $ sudo tar -xvzf bundle.tar.gz
Kieran Kelleher 47.1 90
91 == Anatomy of Embedded Split Install Bundles produced by this Ant Script ==
92
93 {{info title="The Deployment Files"}}
94 The two compressed "ready-to-deploy" bundles are highlighted below
Pascal Robert 64.1 95 [[image:attach:build_artifacts.jpg]]
Kieran Kelleher 47.1 96 {{/info}}
97
98 The notable aspects of the embedded build structure are shown below.
99
100 === Application Bundle ===
101
102 {{info title="Embedded Application Bundle Layout"}}
Pascal Robert 64.1 103 [[image:attach:app_bundle_layout.jpg]]
Kieran Kelleher 47.1 104
105 * Opening the app executable (command line script at bundle root having the application name as its name) and looking at the end will reveal that the WOFrameworksBaseURL references the frameworks inside the webserver embedded bundle.
106 * Examining the Contents/MacOS/MacOSClassPath.txt file will reveal that the java classpath refers to all the jars inside the embedded bundle.
107 {{/info}}
108
109 The application bundle typically gets installed as follows:
110
111 * Install Location = /Library/WebObjects/Applications/
112 * chown (ownership) = appserver:appserveradm
Pascal Robert 64.1 113 * chmod (permissions) = 755 (750 if you wish, but your server login id needs to be a member of appserveradm group to cd into the bundle)
Kieran Kelleher 47.1 114
115 === WebServer Bundle ===
116
117 {{info title="Embedded WebServer Bundle Layout"}}
Pascal Robert 64.1 118 [[image:attach:webserver_bundle_layout.jpg]]
Kieran Kelleher 47.1 119 {{/info}}
120
121 The webserver bundle typically gets installed as follows:
122
123 * Install Location = /Library/WebServer/Documents/WebObjects/
124 * chown (ownership) = root:wheel
125 * chmod (permissions) = 755
126
127 == Compatibility ==
128
129 This script was developed and tested on Mac OS X 10.4.10, Eclipse 3.3.1 and WOLips #4735. It should be compatible with later versions of WOLips and Eclipse. It works with regular WebObjects apps and Wonder based apps. I don't have a Windows Eclipse/WOLips installation, so if you are a Windows user, please feel free to make necessary changes and submit revised build script if this does not run on Windows.