Deploying applications
After you have deployed your NexJ application, you can access it through a supported web browser.
NexJ Admin Console and NexJ System Admin Console are accessed through a web browser by opening a URL with the extension .html
.
NexJ CRM is accessed through a web browser by opening a URL with the extension .htma
.
Info
NexJ strongly recommends clearing or truncating the NJSession table for any upgrade that requires a reseed. Doing so preserves client user states.
Deploying a model
Deploy your application after configuring your application server.
You can deploy more than one model to each application server by using unique names for .ear
archive files.
Depending on your permissions and configuration, you can either deploy using NexJ Studio or manually through the command line.
Dynamic deployment is supported. If you need to change some settings and re-deploy the model, you can do so without stopping and restarting the server.
Deploying a workspace model using NexJ Studio
Deploy any model that is open and available in the Model Library. If you are developing the current model, you can deploy the model without having to create a published .jar
beforehand. The deployment process will temporarily publish the .jar
when deploying to the server.
In order to deploy a workspace model, you must have already configured environment files in the Deployment layer of the model to identify the server and connections that you want to use in your deployment. In addition, the models referenced by the workspace model must be available during deployment.
To deploy a workspace model from NexJ Studio:
- In the toolbar, click the Set Current Model button . The Model Library window opens.
- In the Models tab of the Model Library, select the checkbox for the model that you want to deploy.
- Ensure that all referenced models, including the base model and any mixins, are available.
- If the base model is unavailable, a magnifying glass appears in the Base Version column. Click the magnifying glass icon to locate the model.
- If any mixins are unavailable, a magnifying glass appears in the Upgrade column in the Mixin Models section. Click the magnifying glass icon to locate the model.
- Click Close. The Model view appears with your selected model.
- In the toolbar, click the down arrow next to the Set Current Server button . Choose the server or environment file that you want to deploy to.
- If you selected a server in the previous step, select the associated connection for that server. In the toolbar, click the Set Current Connections button . Choose the connections that you want to deploy with.
- Configure the server settings. When changes are made to settings that require server configuration, for example data sources and channels, the server must be configured before deployment. Configuring before deployment ensures that unconfigured settings do not cause errors.
- To start the configuration process manually from the menu bar, select Project → Configure Server. The configuration process occurs.
- To enable automatic configuration from the menu bar, select Project → Configure Automatically. NexJ Studio will run the configuration process each time you deploy a model.
- Click the Deploy Model button to begin deploying to the application server.
NexJ Studio validates the model during deployment. If warnings are detected during the validation, a dialog box will ask you to confirm that you want to continue deploying. If errors are detected, you will be unable to deploy the model until they are resolved.
Deploying a published model using NexJ Studio
Deploy a published model directly from the Base Models tab. If you do not need to customize or develop the model, using a published model allows you to deploy it without having to open it in NexJ Studio.
Before you deploy the model, ensure the following prerequisites are met:
- The Global environment folder is set in the NexJ Studio preferences, and it points to an existing folder. The global environment folder can be set by selecting Window → Preferences → NexJ Studio.
- The environment or server file that you configured according to the instructions in Creating environment files is copied into this folder. If you have not created the environment or server file, you can use the environment file editor in NexJ Studio to do so. A list of global environments can be accessed from the menu bar by selecting Window → Show View → Global Environments. New files can be added to this list through the View Menu button .
To deploy a published model:
- In the toolbar, click the Set Current Model button . The Model Library window opens.
- Click the Base Models tab.
- If your model is not listed, add it to the list. Click Add. Navigate to the published model and click Open.
- Select your model and click Deploy. The Deploying Model dialog opens.
- In the Server and Connections fields, select the environment or server and connections that you want to use.
The available configurations are taken from the files stored in the global environment folder. - Select the Configure Automatically option. When changes are made to settings that require server configuration, for example data sources and channels, the server must be configured before deployment. The Configure Automatically option ensures that unconfigured settings do not cause errors.
- Click OK to begin deploying to the application server.
NexJ Studio validates the model during deployment. If warnings are detected during the validation, a dialog box will ask you to confirm that you want to continue deploying. If errors are detected, you will be unable to deploy the model until they are resolved.
Deploying a model using the command line
NexJ Studio generates a deployment command for Apache Ant to deploy models, displaying the ongoing process in the console. If you want to deploy models without using NexJ Studio, you can manually enter this command in the command line. You can also automate command line deployment by using scripts.
Enter the deployment command and its arguments on one line within the command line console. Alternatively, you can use a text editor to create a properties file that contains all the properties required to deploy the model.
Command line arguments for deployment
Here is a list of key arguments:
-f <plugin.dir>/<build>/<build.xml>
Specifies name and location of Ant build file (plugin.dir/build/build.xml
) and any desired targets.
Targets server.config and server.deploy configure and deploy to the server.
-Dplugin.dir=<plugin.dir>
Specifies the directory where com.nexjsystems.nexjstudio_version.zip
is extracted.
-Dbuild.jnlp=true | <false>
Specifies whether the deployment is building Java Client. If set to false, keystore-related properties can be omitted.
-Dout=out
Specifies the out
directory, for example, C:\work\out
. This is where deployment files are created.
-Dproject=<project>
Specifies the name of the project. The value must be .tmp
. It is created in the out directory specified in -Dout.
-Dbase.jar=<model.jar>
Specifies the name and location of the published model file (.jar
). If the model uses mixins, they must be contained within the publish
folder of the out
directory.
-Dserver=<server.config>
Specifies the name and location of the server configuration file (.server
) or environment configuration file (.environment
). Omit if the automatic J2EE container resource configuration is not needed.
-Dconnections=<connections.config>
Specifies the name and location of the connections configuration file (.connections
). Omit if using an environment file in -Dserver
.
-Dwebsphere.dir=websphere.dir
Specifies the folder location of the WebSphere Application Server.
-Dcipher.master.password=<cipher.password>
Specifies the master encrypted password used by the application server. Begins with a master:
prefix, followed by the encrypted password string. It is recommended to use a master password file instead.
-Dcipher.master.url=<cipher.password.url>
Specifies the name and location of the master password file (master.pwd
). Use -Dcipher.master.url to point to the password file instead of specifying the password directly in -Dcipher.master.password in case your operating system does not hide command line arguments from other users.
-Dkeystore.file=<keystore>
Specifies the name and location of the keystore file (.p12
).
-Dkeystore.password=<keystore.pass>
Specifies the password used in the keystore file specified by -Dkeystore.file.
Using command line arguments
Use the command line console to deploy a model without the help of NexJ Studio. The command line is necessary if you cannot use NexJ Studio in the deployment environment, or if you require the deployment process to be automated with a script.
You will require the following to use this method:
- Apache Ant
- Java Development Kit
- WebSphere Application Server
- NexJ Studio plugin folder (
com.nexjsystems.nexjstudio_<version>
) - Published model
.jar
file
You will need to specify the location for these items in the command line. For the NexJ Studio plugin folder, either NexJ Studio should be installed or the plugin should be extracted on the hard drive. If NexJ Studio is installed, the plugin folder is located in NEXJ_HOME/version/plugins
where NEXJ_HOME
is the installation directory.
To deploy a model using the command line:
- Open your command line console.
Enter the deployment command at the prompt. You can run the Ant program directly by specifying its location or you can change your directory to the
bin
folder and run the program from there. A sample deployment command looks like this:c:\apache-ant\bin\ant -f "c:/work/plugins/com.nexjsystems.nexjstudio_version/ build/build.xml" -Dplugin.dir="c:/work/plugins/com.nexjsystems.nexjstudio_version/" -Dtemp.dir="c:/work/temp/" -Dpublish.dir="c:/work/mixins/" -Dout.dir="c:/work/out/" -Droject=".tmp" -Dbase.jar="C:/work/out/publish/nexj-meta-core.jar" -Dserver="C:/work/env/UnitTest.environment" server.config server.deploy
The deployment process executes. Ongoing results are displayed in the console window until the deployment finishes or an error occurs.
If there is an error, the console displays the problem before halting execution.
Using a properties file
Use a properties file to store the arguments for deployment. For information on arguments, see Command line arguments for deployment.
You will require the following to use this method:
- Apache Ant
- Java Development Kit
- WebSphere Application Server
- NexJ Studio plugin folder (
com.nexjsystems.nexjstudio_<version>
) - Published model .jar file
You will need to specify the location for these items in the command line. For the NexJ Studio plugin folder, either NexJ Studio should be installed or the plugin should be extracted on the hard drive. If NexJ Studio is installed, the plugin folder is located in NEXJ_HOME/version/plugins
where NEXJ_HOME
is the installation directory.
To deploy a model using the command line with a properties file:
- Open a text editor of your choice and create a new file.
Enter the properties of your deployment, with each property on its own line. Remove the
-D
prefix from each rgument. A sample.properties
file looks like this:plugin.dir=c:/work/plugins/com.nexjsystsems.nexjstudio_version/ temp.dir=c:/work/temp/ publish.dir=c:/work/mixins/ out.dir=c:/work/out/ project=.tmp base.jar=C:/work/out/publish/nexj-meta-core.jar server=C:/work/env/UnitTest.environment
Note
Ensure that forward slashes (/) are used when specifying directories and no whitespace is resent at the end of each line. If the file is not properly formatted, the command will fail with unrelated error messages.
Save the file with the
.properties
extension, for example,core_deploy.properties
.Open your command line console.
In the command line, enter the deployment command using the -propertyfile option.
A sample command using the.properties
file from above looks like this:c:\apache-ant\bin\ant -propertyfile "c:/work/core_deploy.properties" -f "c:/work/plugins/com.nexjsystems.nexjstudio/build/build.xml" server.config server.deplo
The deployment process executes. Ongoing results are displayed in the console window until the deployment finishes or an error occurs.
If there is an error, the console displays the problem before halting execution.
Deploying multiple models on a single server
It is possible to deploy multiple models on a single server and access a selected model using a unique URL.
You can deploy completely different solutions or multiple copies of the same solution, possibly for different versions of the model.
Setting up multiple model deployment on a single server
By default, when a model is deployed, its environment name or a derivation of the project namespace is added as a suffix to the deployed enterprise archive .ear
file, for example, nexj-finance.ear
. Multiple .ear
files can be deployed onto a single application server and accessed using the URLs specified in the server or environment files. The file name and URL must be different for each model so they do not cause conflicts. However, there are other properties that must be altered in order for multiple models to function without problems.
The following properties must be customized:
Object queue port
By default, the object queue port is set to 1111. This port must be different for every deployed model. To customize the object queue port, open the server or environment file. In the Properties view, locate the messagePort property, under the Queueing category. A unique messagePort
must be added for each model.
Ports
Ensure that there are no port conflicts between models. For example, if two models contain UDP channels, they must be configured to use different ports.
Environment names
If you are deploying the same model multiple times, you must enter a unique environment name in the server or environment files. The name can be entered in the Properties view, in the name property within the Deployment category. It is possible to deploy .ear
files without a suffix by entering an empty name attribute. An empty name attribute generates a file called nexj.ear
.
HTTP server URLs
By default, the server path is /nexj/env
, where env
is specified in the source as a top level attribute of name or taken from a part of the project namespace if no attribute exists. Specify a unique URL for each model. Different environment names will ensure that unique server URLs are generated by default.
See Running deployed applications for more information.
Dynamic metadata deployment of models
With dynamic metadata deployment, you can redeploy updated model metadata to an application server without having to stop and restart the application server. Using dynamic deployment, you can configure environment files without bringing the server down.
Model metadata is uploaded into the database and is stored until activated. Before you can use dynamic deployment, you must enable the feature in your environment or server files and specify a user with the deployment:DeployMetadata privilege.
Dynamic resource pooling supports dynamic deployment of changes to channels. For example, you can add a new file channel and update metadata for your model without stopping the server.
Dynamic deployment is not available when changing cipher keys associated with encrypted columns.
Deployment Tool overview
Dynamic metadata deployment is performed in NexJ Studio with the Deployment Tool.
The Deployment Tool contains a number of commands:
upload
Uploads a model to the server.
activate
Switches the active deployment to an existing model on the server by specifying an ID. To activate the original metadata in the deployed .ear
file, select the Static Deployment option. If the server is not running, select the Force Update to Database option to directly update the database to set the active deployment.
listdeployments
Lists the deployments that have been added to the server with the upload command. The ID, creation time, and description of each deployment is displayed in the console.
listmodels
Lists the individual models available on the server, including all base and mixin models that are contained within a deployed model. The ID, name, version, checksum, and creation time of each model is displayed in the console.
removedeployment
Removes a single deployment, specified by ID. To remove associated models with the specified deployment that are no longer in use, select the Remove Associated Models option.
removemodel
Removes a single model, specified by ID.
clone
Clones a single deployment, specified by ID.
Setting up dynamic metadata deployment
Before using dynamic deployment, you must enable the feature and add a data source connection for the data source containing the deployment metadata.
To enable dynamic deployment:
- In the Deployment layer, double-click the environment or server file for the application you are using. The file opens in the editor window.
- In the Overview tab, select the Dynamic checkbox to enable dynamic metadata deployment. Enabling Dynamic adds the mixin models necessary for dynamic deployment. The Deployment data source is added to the list of available data source connections.
- Verify that the Deployment User and Password fields match the login for the user who will deploy metadata.
- In the environment or connections file, select the Data Source Connections tab.
- Click the Select button . Add the data source connection for the Deployment data source.
Configure the Deployment data source. See Configuring data source connections for more information.
Info
If you want to store uploaded models in the same database as the DefaultRelationalDatabase data source, copy the settings over to the Deployment data source.
- Use the Data Load Tool to create tables to store deployment metadata:
- In the toolbar, click the arrow beside the Run Tool button and select Data Load Tool. The Data Load Tool dialog opens.
- In the Model section, select Current.
- In the Server and Connections section, specify the server and connections file for the model to use.
- In the Options section, in the Command field, select recreateschema. In the Data Source field, select
Deployment
. - Click Run to create the system schema.
Dynamic deployment is now enabled.
Before the Deployment Tool commands can be used, the deployment user must be granted the deployment:DeployMetadata privilege. For more information about assigning privileges, see Configuring privilege groups.
Uploading a model using dynamic deployment
Upload new model metadata using the Deployment Tool in NexJ Studio. Model metadata is placed into the database and can be activated later.
Before you can use any of the Deployment Tool commands, the deployment:DeployMetadata privilege must be granted to the deployment user. For more information about assigning privileges, see Configuring privilege groups. Also, ensure that your server or environment file uses an absolute path for the HTTP server URL. For example,
http://localhost:8080/nexj/app.
To upload a model using dynamic deployment:
- In the toolbar, click the arrow beside the Run Tool button and select Deployment Tool.
The Deployment Tool dialog opens. - In the Model section, select the model containing the server and connection files you want to use for deployment.
- In the Server and Connections section, specify the server and connections to use for uploading the model to the server. File paths appear in the Server and Connections fields in the Options section.
- In the Options section, in the Command field, select upload.
- In the Options section, select the model you want to upload. The base model and any mixin models should be added automatically. If not, ensure the proper models are added by clicking the Browse button beside the Mixin Models section and selecting the appropriate models.
- Enter a meaningful description in the Description field. This field is required for uploading the model.
- Click Run. The model uploads to the server using the selected server and connections files.
After deployment is complete, a message appears in the console with an ID. Copy this ID to use for activating the model later.
Activating uploaded models
Use the Deployment Tool to activate a deployment that has been uploaded to the server.
Before you can use any of the Deployment Tool commands, the deployment:DeployMetadata privilege must be granted to the deployment user. For more information about assigning privileges, see Configuring privilege groups.
The ID of the uploaded model is required to activate it. This ID is displayed in the console after uploading a model, or you can use the listdeployments
command to display the IDs of all uploaded deployments along with their descriptions.
To activate an existing deployed model:
- In the toolbar, click the arrow beside the Run Tool button and select Deployment Tool. The Deployment Tool dialog opens.
- In the Model section, select the model to use for executing deployment.
- In the Server and Connections section, specify the server and connections to use for activating the uploaded model on the server. File paths appear in the Server and Connections fields in the Options section.
- In the Options section, in the Command field, select activate.
- In the Id field, enter the ID of the model you want to activate.
- Click Run.
The model is now activated on the server.
Running deployed applications
After you have deployed your application, you can access it through NexJ Studio, or through a supported browser by specifying a URL.
Launching applications from a browser
After a model is deployed, its applications become available for access through a supported web browser.
To launch an application, enter the application URI (Uniform Resource Identifier) into the browser navigation bar. The URI format depends on whether the application is a portal application, such as NexJ CRM, or a flat web application, such as NexJ Admin Console or NexJ System Admin Console.
Launching portal applications from a browser
The format of the URI is the following:
http://<serverName>:<port>/<context>/<modelName>/SysPortal.htma?app=<appName>
serverName
The name of the server. If you are running your own webserver, this value is localhost
.
port
The default port is 8080
. If your production system uses the default HTTP port 80, then you do not have to specify the port.
context
The directory on the application server where the model resides. This value is usually nexj
.
modelName
This value is optional and only used when multiple models are deployed on the same server. The name of the model. For example: US-Finance
.
appName
The name of the application as defined in metadata. For example: Contact
.
Info
Advanced users, such as developers, can specify additional attributes after the application name in the URI, by adding a string of the following format: <&attribute=value
>. For more information about additional supported attributes, see Attributes and data types.
Launching flat web applications from a browser
The format of the URI is the following:
http://<serverName>:<port>/<context>/<modelName>/<appName>.html
serverName
The name of the server. If you are running your own webserver, this value is localhost
.
port
The default port is 8080
. If your production system uses the default HTTP port 80, then you do not have to specify the port.
context
The directory on the application server where the model resides. This value is usually nexj
.
modelName
This value is optional and only used when multiple models are deployed on the same server. The name of the model. For example: US-Finance
.
appName
The name of the application as defined in metadata. For example: Admin
.
Launching applications from NexJ Studio
You can launch an application from a deployed model using NexJ Studio.
To run your NexJ application from NexJ Studio:
- In the NexJ Studio toolbar, click the down arrow next to the Set Current Model button and select a deployed model.
- Click the down arrow next to the Set Current Server button and select either an environment file or a server file.
- In you selected a server file in the previous step, click the down arrow next to the Set Current Connections button and select a connections file.
If you selected an environment file in the previous step, this button will not be active. - Click the Set current user button and select the user that you want to access the application as.
If the user you want is not listed, add it by selecting Manage Users... → Add and setting the login name of the new entry. The default NexJ System Administration user name isnexjsa
. - Click the down arrow on the Run application button , and select one of the following application types:
- If you will launch a flat web application, such as NexJ Admin Console or NexJ System Admin Console, select Flat Web.
- If you will launch a portal application, such as NexJ CRM, select the caption that you defined in the portal application strings file. For example, select NexJ Customer Relationship Management (NexJ CRM) .
The application type is selected in the menu.
- Click the down arrow on the Run application button and select the application that you want to launch. For example, select
NexJ CRM
.
The application launches in your default web browser.