ptg 72 Chapter 4 Configuration Files Explained The default Maven repository is located at the following: http://repo1.maven.org/maven2/ To see information about your current local repository, such as its location on your local file system and which module groups are available, you can execute the following from the Web- Sphere sMash CLI directory: zero repository info This command will also tell you which module group is currently being used by the CLI. The CLI can only use one module group at a time. Any CLI commands will execute from mod- ules in the currently active module group. Likewise, any applications created will be created using modules from the currently active module group. To see which module group an applica- tion is using, you can execute the following command from the application’s directory: zero modulegroup info You c an se e w hi ch sp ec ifi c m od ul es a m od ul e g ro up co nt ai ns by exe cu ti ng the f ol low in g: zero modulegroup list If you want to use multiple module groups for different versions of your application, such as a stable and experimental version, you must make sure your CLI is pointing to the correct module group. You must switch the CLI to use the new module group: zero modulegroup switch <modulegroupname> After switching the command line, you can create the application using the create com- mand. You can also use the modulegroup switch command from within an application's direc- tory to switch the application to a new module group. In this case, the application will be resolved again against the new module group. You will probably need to run zero update to pick up com- patible versions of modules from the new module group. NOTE The preceding instructions apply to CLI users. If you are using App Builder, mod- ule group switching is handled for you. You need to specify only the correct module group on the application creation dialog. If you are using Eclipse, the module group can be selected through the WebSphere sMash Preferences dialog. Table 4.3 Remote Zero Repositories Versi on Module Group Name URL 1.0.x stable https://www.projectzero.org/sMash/1.0.x/repo/ 1.1.x stable https://www.projectzero.org/sMash/1.1.x/repo/ Latest experimental https://www.projectzero.org/zero/monza/latest/repo/ Download from www.wowebook.com ptg Dependency Management with Ivy 73 Remote Resolvers When you executed the zero modulegroup info command, you may have noticed that the list of resolvers was displayed. Resolvers are CLI components that are responsible for matching modules in a particular location or locations. Understanding the different resolvers will help you understand how WebSphere sMash finds dependencies for your application. • chain resolver—Simply executes multiple resolvers in a particular order • zero resolver—Searches a remote Ivy repository, typically stored on www.pro- jectzero.org • maven resolver—Searches a remote Maven repository Local Resolvers • workspace resolver—Looks for modules that are peers to the application that is being resolved. The workspace resolver executes first in the local resolvers. Note that the revision number in the ivy.xml does not matter to the workspace resolver. The work- space resolver considers the module name to be sufficient for a match. This behavior is of primary benefit to Eclipse users who are developing multiple related modules in a single Eclipse workspace. • userhome resolver—The standard resolver that searches the application’s module group in the local repository. The first time you invoke “resolve” on an application, it executes the local resolvers followed by the remote resolvers, until all dependencies are resolved. The order looks like the following: workspace resolver > userhome resolver > zero resolver > maven resolver During the resolve, the first matching module that is found for each pattern is copied into your local repository under the appropriate module group. The resolvers will resolve nested dependencies as well and inform you of any conflicts.After the resolve has completed successfully, the versions of modules that were found are written into a file called within the application at .zero/private/resolved.properties If you run a resolve against the same application again, it will attempt to find the specific versions of modules described in the resolved.properties file rather than use pattern match- ing. Furthermore, only the local repositories will be searched. If the CLI cannot find these ver- sions, the resolve command will fail. You will be instructed to perform a zero update instead. The purpose of the zero update command is to update your application to point to the latest modules in your local repository that match the patterns declared in your ivy.xml. However, what you probably want is to first update the modules in your local repository and then update Download from www.wowebook.com ptg 74 Chapter 4 Configuration Files Explained your application to point to those new modules. This procedure requires executing two com- mands within your application’s directory, as follows: zero modulegroup update zero update If you want to see a detailed report of the modules that were resolved for your application, there is an XML file in your application’s /reports directory with a name that matches the pattern zero-<module>-default.xml. If you open up this XML file with a web browser, you will get a nicely formatted report describing the specific versions of modules that were found and which resolver found them. Finally, if your resolve or update accidentally breaks your application, you can undo the damage. WebSphere sMash maintains a history of the last resolve or update command. To undo the last command, execute the following: zero rollback Environment Configuration We have discussed how to create your application configuration parameters in zero.config and how to declare your application’s dependencies in ivy.xml. We will now look at how to config- ure your application for different environments, and at what additional configuration information your application can retrieve at runtime. WebSphere sMash core modules provide a number of configuration URIs that are useful to developers. Some of these URIs should be set in the zero.config file because they are read-only at run-time. Other URIs can be read or set programmatically from your application using the Global Context APIs. The URI’s type and default value, if any, are shown in parentheses below (type/default). Useful Information About Your Application The following configuration URIs cannot be set in zero.config or using the Global Context API, but they are available for your application to read as part of the config zone of the Global Context: • /config/name (String)—This URI provides the name of the application. It might be important to read this value rather than use a hard-coded string, because someone could have created a wrapper around your application, giving it a different name. • /config/dependencies (List)—This URI points to a list of the module names of your application’s dependencies, such as ["zero.core", "zero.data"]. • /config/dependencies/<moduleName> (String)—By adding the moduleName of the dependency to the URI, you can retrieve the directory for that dependency. Download from www.wowebook.com ptg Environment Configuration 75 Runtime Configuration zero.config contains a number of runtime configuration URIs that are set when your applica- tion is started. Most of these values can be read (but not set) in your application using the Global Context API: • /config/http/port (Long/8080)—Set the value of this URI in zero.config to con- figure the port that the application will listen on for HTTP requests. The value can be set to –1 if you only want the application to respond to HTTPS requests. • /config/http/ipAddress (String)—You can set the specific IP address of the Web- Sphere sMash HTTP server in zero.config using this URI. • /config/https/port (Long/0)—Set the value of this URI in zero.config to config- ure the port that the application will listen on for HTTPS requests. The default HTTPS port is 0, which means HTTPS is not open. • /config/https/ipAddress (String)—You can set the specific IP address of the WebSphere sMash HTTPS server in zero.config using this URI. • /config/runtime/mode (String / “development”)—The default for this URI is “development”. When you are ready to move your application to production mode, this value should be changed to “production” in zero.config. Changing the value to “pro- duction” changes request timeouts, maximum numbers of requests, and application recycle frequencies to be more suited to a production environment. • /config/contextRoot (String)—This URI sets the context root for the application. The value is a URI path starting with a slash. The URI should be set in zero.config, but it can be read by an application using the Global Context API. With the context root set, requests to your application will take the form http://myhost:8080/ <contextRoot>/index.html. • /config/externalUriPrefix (String)—This URI can be set in zero.config to specify the full scheme, hostname, and port (for example, http://www.ibm.com:8080) for use in generating absolute URIs when the applica- tion is deployed behind a reverse proxy. The WebSphere sMash URIUtils API described in Chapter 11, “Framework Components,” uses this field to generate absolute URIs. • /config/id (String)—This URI contains the process ID of the running application. This information is useful for debugging. Response Configuration WebSphere sMash applications have some default behaviors for returning responses to web requests. The default responses can be overridden in zero.config to help you debug or optimize Download from www.wowebook.com ptg 76 Chapter 4 Configuration Files Explained your application. You can also set behaviors for returning responses based on browsers requesting resources in different languages: • /config/json/prettyPrint (boolean/false)—If this value is set to true in zero.config, WebSphere sMash will render JSON responses in a more legible multi- line format rather than a single-line format. These “pretty print” responses are easier to read in a browser or file editor and are useful for debugging. • /config/compressResponse (boolean/false)—If you want to use gzip compression of responses, set this URI to true in zero.config. The client request will need to set the header Accept-Encoding: gzip,deflate. • /config/exitCode (Integer/0)—If you are writing a config event handler for your application, you can set the exitCode to a nonzero value when you encounter an error loading the configuration. The application will terminate after the handler exits. • /config/fileserver/contentNegotiation (boolean/false)—When this value is set to true in zero.config, the Accept-Language request header is used as a file exten- sion to find an appropriate file to serve if the requested resource does not exist. The value of the Accept-Language header is appended to the filename for the search. For example, if Accept-Language was set to en, a request for sample.html would search for sample.html followed by sample.html.en. • /config/fileserver/defaultLanguage (String/server language)—When content negotiation is enabled, the final option for locating an appropriate resource is to append the default language as a file extension. For example, if Accept-Language is set to ja and defaultLanguage is set to en, the search order for sample.html would be sample.html, sample.html.ja, and sample.html.en. • /config/fileserver/directoryBrowsing (boolean/false)—If directory brows- ing is enabled, you will be able to use a web browser to browse virtual directories under your app’s public directory. For example, http://myhost:8080/test would list the files and directories in the virtual directory /public/test of the running application. • /config/fileserver/expires/<.extension> (Long/0)—The default cache expiration for static served files is 0 seconds. You can specify a maximum age for files with a particular file extension using this Global Context URI. The value is set in the Cache-Control header for files of that type. For example, putting the following state- ment in zero.config would set the max-age for .html files to 180 seconds: /config/fileserver/expires/.html=180 • /config/fileserver/setEtag (boolean/true)—Setting this flag in zero.config causes the eTag response header to be set for served files for caching purposes. Download from www.wowebook.com ptg Command-Line Interface (CLI) Config 77 Command-Line Interface (CLI) Config When you first download the WebSphere sMash CLI, you get a small ZIP file with just a few files in it. This is the bootstrap code for the CLI. The first time you execute any zero command (even help or nothing), the bootstrap code will prime the local repository from the remote repository defined in /config/bootstrap.properties. Although you can change the information speci- fied in bootstrap.properties, you will not typically need to do so unless you are using your own enterprise repository. When the CLI is bootstrapped, the bootstrap.properties file will not be used again. If you are using a proxy to access the Internet, you will need to configure the proxy settings by editing the ZERO_OPTS line in the zero.bat file, as described in Chapter 1, “Installing the IBM WebSphere sMash CLI.” There are a number of other interesting configuration files for the CLI, as follows: • local.properties—Enables you to set HTTP timeouts and the location of your local Ivy repository • logging.properties—Enables you to set logging and tracing levels and log and trace file-handling options for the CLI App Builder Configuration The App Builder configuration can be found in your <zerohome>/installed/appbuilder/ config directory. The most commonly changed configuration parameter in the App Builder’s zero.config is the port on which AppBuilder runs. Listing 4.5 is a default zero.config file for App Builder. Listing 4.5 Sample zero.config File # HTTP port (default is 8080) #/config/http/port = 8080 # Runtime mode (default is "production") #/config/runtime/mode="development" Eclipse Configuration The WebSphere sMash Eclipse plugin requires you to configure the location of a CLI before use. This configuration is found under Window > Preferences in Eclipse. The Zero home field should point to the zero directory of your CLI installation (see Figure 4.2). After the CLI location is provided, a list of available module groups are displayed in the drop-down list. Module groups are part of WebSphere sMash’s Ivy dependency management sys- tem. See the section on Ivy dependencies in this chapter for more information on module groups. Download from www.wowebook.com ptg 78 Chapter 4 Configuration Files Explained Figure 4.2 Eclipse preferences If the Resolve Automatically check box is selected, modules in the workspace will auto- matically be resolved when a change is detected that would require resolution. Examples of changes that require resolution are changes to a module’s ivy.xml file or creation of a new module. If the Run Update Instead of Resolve check box is selected, resolves will automatically find the latest module dependencies in the local repository rather than the ones that were recorded during the last successful resolve. For new users of WebSphere sMash, we recommend selecting both of these check boxes. More information on dependency resolution can be found in the Ivy dependencies section of this chapter. JVM Configuration WebSphere sMash uses a utility called the Zero Socket Opener (ZSO) to manage the life cycle of WebSphere sMash applications. When ZSO starts a WebSphere sMash application, it starts a new Java Virtual Machine (JVM™). You can provide ZSO with Java command-line arguments for your application by using the /config/zso/jvmargs Global Context URI in your zero.config. The format is a JSON array of properties to pass to the JVM—for example, /config/zso/jvmargs += [ "-Duser.home=/home/zero" ] NOTE The WebSphere sMash Eclipse plugin does not use ZSO to launch applications. Instead, Eclipse launches the application JVM directly using a Run profile. So, you can pass JVM arguments as part of the Run profile in Eclipse. Download from www.wowebook.com ptg Command-Line Interface (CLI) Config 79 Overriding Configuration Parameters WebSphere sMash provides a number of ways to override configuration parameters. If you need to override a configuration parameter in a dependency, the easiest way is to set the parameter in your application’s zero.config. As mentioned previously, the application’s zero.config is processed first, and subsequent assignments to the same Global Context URI will be ignored. There are times when you may want to override a configuration parameter in an application you are deploying, but you don’t want to modify the application’s zero.config file itself. For example, if the application is stored in your local repository as a packaged module, you can take advantage of WebSphere sMash’s capability to update dependencies to retrieve updates to the application whenever they are available. In another scenario, you have unzipped an application into a local directory, and you want to isolate configuration changes from the application direc- tory itself. The first mechanism to override the configuration is to create a wrapper application. This procedure consists of creating a new application that includes the application you want to over- ride as a dependency. You can name the new application whatever you’d like, but you should cre- ate it in a peer directory to the application you want to override. For example, if your apps are stored in a myapps directory, you can create an app called wrapper by executing the following from the CLI: cd myapps zero create wrapper linkto myorg:myapp linkto is a special instruction that tells the create command to create a default applica- tion with the specified module as a dependency. If you look at wrapper’s ivy.xml file, you will see this dependency declaration: <dependency name="myapp" org="myorg" rev="+"/> Because we didn’t specify a specific revision for the link, a + was inserted in the depend- ency. + means “the latest” in a dependency declaration. The create command executes a resolve after the create completes. myapp could exist in the myapps directory as a peer to wrapper, in which case it would be found by the workspace resolver. If myapp were in the local repository, it would be found by the default local resolver. If myapp existed only in a remote repository, it would be found by a remote resolver. Regardless of where myapp is found, you now have a wrapper application with which to work. You can edit wrapper’s zero.config file to override the desired parameters from myapp. Then, you can start the wrapper application, which will behave just like myapp only with your new configuration parameters. There is another benefit to this approach. Because wrapper is a full application with full virtual directory support across its dependencies, you can add things like HTML or CSS files to wrapper to override or enhance the original versions in myapp. Download from www.wowebook.com ptg Another option for overriding configuration parameters is to specify pre- or post-configura- tion files as startup parameters for your application. Pre files are processed before any other zero.config files. Post files are processed after all other zero.config files. For example: zero start –pre c:\test\before.config –post c:\test\after.config Reverse Proxy Server Configuration Every WebSphere sMash application runs on its own port. If you are running multiple WebSphere sMash applications in a production environment, you probably will want to present a single-port view of all your applications. You can do this by configuring a reverse proxy server in front of your WebSphere sMash applications. We mentioned the contextRoot and externalUriPrefix configuration URIs in the pre- vious section on Common Configuration URIs. Both of these parameters should be configured when using a reverse proxy server. A full discussion of configuring a reverse proxy server is beyond the scope of this book. The WebSphere sMash Developers Guide contains an excellent description of how to set up a reverse proxy for WebSphere sMash on an Apache server using the mod_proxy module. We rec- ommend that you refer to this documentation for more detail on this topic. Conclusion In this chapter, we introduced the primary ways to configure WebSphere sMash and WebSphere sMash applications. We discussed configuration of the CLI, Eclipse, and applications. We talked about dependency management and virtual directories. However, we purposefully deferred dis- cussion of some configuration topics to later chapters where they are discussed in context to the topic being covered. 80 Chapter 4 Configuration Files Explained Download from www.wowebook.com ptg 81 The global context is a part of WebSphere sMash that provides unified access to environmental, application, and user-specific data. The global context consists of several zones, each forming a namespace that is rooted at “/”. Each zone serves a particular purpose, providing data for the application that is applicable for a certain scope. In this chapter, we look at each of these zones in turn and then learn how to access these zones in Java, Groovy, and PHP. Zones The global context is divided into several zones by default. The standard set of zones includes the config, request, event, tmp, app, connection, user, and storage zones. These zones provide a wide range of scoped data and allow applications to add their own information. Zones come in two flavors: persistent and non-persistent. Persistent zones store their data in a data store, such as a database, so that it is available between restarts of the application. Non-persistent zones are not serialized to disk, so the data stored in these zones are available only for the lifetime of the application. Non-Persistent Zones There are five default non-persistent zones: config, request, event, tmp, and connection zones. Config Zone (/config) Data in the config zone is loaded from the application’s configuration files. The config zone data is available for the entire lifetime of the application and is globally visible. The config zone data is modifiable, but changes are effective only for the lifetime of the application and will be C H A P T E R 5 Global Context Download from www.wowebook.com . myapp is found, you now have a wrapper application with which to work. You can edit wrapper’s zero.config file to override the desired parameters from myapp. Then, you can start the wrapper application,. c: estefore.config –post c: estafter.config Reverse Proxy Server Configuration Every WebSphere sMash application runs on its own port. If you are running multiple WebSphere sMash applications in a production. port (for example, http://www .ibm. com:8080) for use in generating absolute URIs when the applica- tion is deployed behind a reverse proxy. The WebSphere sMash URIUtils API described in Chapter