This lesson walks you through the set up of your local environment while becoming familiar with some of NexJ Studio's features and functions.
Prerequisites
The following are required to successfully use this training:
A computer with a minimum of 16 GB of RAM running Microsoft Windows 7 or Microsoft Windows 10. The 64-bit version of the operating system is recommended.
2 GB of free disk space
Java Runtime Environment (JRE) 8 or later
A local instance of MSSQL 2012 or MSSQL 2016, set up and configured
An internet connection capable of accessing the nexj.com domains.
To check if the prerequisites are installed:
From your Windows command prompt, type java -version. You should be running version 7 or later.
BASH
java version "1.8.0_111"
Java(TM) SE Runtime Environment (build 1.8.0_111-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.111-b14, mixed mode)
Run SQL Server Management Studio and log in as sa, using SQL Server Authentication (rather than Windows Authentication).
If you need to install MS SQL:
Download and install Microsoft SQL Server 2012 Express with Advanced Services or later.
During MSSQL installation
To ensure that SQL Server Management Studio is included, install SQL Server with Tools, for example Microsoft SQL Server Express 2014 with Tools (ExpressAndTools 64BIT\SQLEXPRWT_x64_ENU.exe).
During installation, it is best to set the alias of the system administrator to "sa" and set a password. This is required for creating databases from within Studio.
During installation, ensure that "mixed authentication" is on (both SQL Server authentication and Windows authentication).
In Microsoft SQL Server Configuration Manager, enable TCP/IP and set the TCP Port to 1433 for IPAll (this step is required).
Enabling TCP/IP and setting the port to 1433
Open Microsoft SQL Server Configuration Manager from the start menu.
Expand SQL Server Network Configuration and click Protocols for SQLEXPRESS.
Double-click TCP/IP.
On the Protocol tab, set Enabled to Yes.
On the IP Addresses tab, for every IP entry (IP1, IP2, IP3, ...) set Enabled to Yes.
At the very bottom of the IP Addresses tab, for IPAll set the TCP Port to 1433 (this step is required).
Click OK. You will be warned that the changes have been saved, but will not take effect until the service is stopped and restarted.
Click SQL Server Services, then right-click SQL Server (SQLEXPRESS) and select Restart.
Open SQL Server Management Studio and login as sa and choose SQL Server Authentication . If you are unable to do so:
Open SQL Server Management Studio and connect to server using Windows Authentication.
Navigate to Security > Logins. Right-click on SA and set the properties.
On the General page, set the Password.
On the Status page, ensure that Login is Enabled.
Close and re-open SQL Server Management Studio.
Login with sa, and SQL Server Authentication.
We recommend that you limit the maximum memory available to the instance (for example, 512MB) and the maximum worker threads (for example, 100). To do this:
Right-click on your SQL instance name > Properties > Memory and adjust the Maximum server memory.
Right-click on your SQL instance name > Properties > Processors and adjust the Maximum worker threads.
Installing NexJ Studio for training
For predictable results during this training, install into c:\nexj_studio. If you install into a different folder, many of the samples and instructions in these guides will not work.
Create a folder called c:\nexj_studio\.
In the file system, navigate to \\tor-sv-file\Documentation\TrainingFiles\ and copy nexj-studio-13.9-training.zip
into c:\nexj_studio. If you are a client, contact your NexJ team to request a copy of the zip file.
Unzip the file contents to c:\nexj_studio. This should create a subfolder named 13.0-training.
Right-click on nexj-studio-13.9-training.zip and select 7-Zip/Extract Here if you use 7-zip to manage archives.
The file structure you end up with should be as follows:
From this folder, create a shortcut for nexjstudio.exe and place it in a convenient location.
When you launch NexJ Studio for the first time (with nexjstudio.exe), the Welcome screen opens. If you receive a message indicating that your Classpath variable NEXJ_PLUGIN has been updated, dismiss the dialog. If you see an "Updates available" dialog, dismiss this as well.
Click Getting started on the Welcome screen to read a bit about NexJ Studio's views.
NexJ Studio tour
NexJ Studio provides a set of tools for working with your application and services' designs. These are called models.
The above figure shows the main window for NexJ Studio. You can rearrange the views and editors in any way that suits your needs. If you want to reset NexJ Studio back to its default settings, select the Window > Perspective > Reset Perspective menu options.
The Model Navigator is located in the left-hand side of the window and organizes the components of your model into architectural layers.
Presentation Design and test user interface components
Classic Presentation Legacy user interface designs (deprecated)
Business Model Model business concepts in classes, class relationships, business logic, persistence mapping, enumerations, and class diagrams; long-running business processes in workflows; and complex business rules in rule sets as well as support for unit testing.
Security Model system privileges.
Persistence Design physical storage including data sources, upgrades and data extracts (dumps).
Integration Model communication with external systems including messages, transformations, services, channels, and interfaces.
Resources Maintain common framework capabilities such as localization, translation and common code libraries.
Deployment Manage your deployment environments for servers and connections e.g. Staging, User Acceptance, Performance, Production...
Documentation Manage books, chapters and images of solution documentation. This is for DITA documentation and is deprecated.
To toggle from Hierarchy mode to Layer mode, click the Show Hierarchy button at the top of the navigator. Items from base models or mixed-in models are displayed in the navigator as grey ; mixed-in items have a little "m" on them ; new items display in color ; and customized items display with color and a strike symbol .
Although items from base or mixed-in models can be customized by using the Customize right mouse button menu item on selected elements, when possible, augments should be used.
The name of the currently open model is displayed at the top of the navigator. For example:
If you are managing more than one model, you can switch between models using the View Menu at the top of the navigator.
You can restrict your view to only local items by selecting the Hide Base Elements menu item from the View Menu.
You can include mixed in elements from your current environment file in the navigator by selecting the Show Environment Mixin Resources menu item from the View Menu.
The model navigator can be docked by selecting its minimize button (at the top right of the navigator).
Editors launch in the center of the screen for whatever items has been opened. They are typically opened from the model navigator or by using Ctrl+Shift+Dto launch Open Model Entry or press Ctrl+Shift+R to select any resource in your model.
Each of the model elements has a specialized editor. For example, there is a Class Diagram Editor for class diagrams and a Message Editor for messages.
When the editor is open, it synchronizes with the outline view. You can choose the most efficient approach for you to locate or add/delete a sub-item. see 5.
Most editors have a set of tabs across their bottom to group properties. e.g. Overview, Attributes, Events, Persistence, Source...
The source tab in an editor allows you to edit the XML directly with copy/paste, ... This is very handy at times.
You can also open files in the Java perspective with "Open with... text editor" to work directly with the XML
Editors can be tiled or minimized.
Help on the currently selected item in an editor automatically displays in the status bar in the bottom-left corner of the screen. Press Shift+F2 to show more help, if available.
The Console view displays console output when you are testing your model with the Server Console or other tools.
The Console view supports useful capabilities, such as scroll lock, show the console when a change occurs (or not), show the console only on errors, and pin the console.
In this same area, there are views for problem reporting, search results, the upgrade editor and more.
The Properties List view displays the properties of the currently selected item in the active editor.
The Outline view displays a tree of all the parts of the current item being edited and can be used for navigation and editing.
The toolbar provides quick access to tools for NexJ Studio, which include:
Set current model Opens the Model Library and lets you select and manage all the models in your environment.
Publishing a model
A model is simply your design represented in a set of .xml and .js files. This is usually on disk in a project folder in your workspace. In the Model Library, you may "publish" your model to a .jar file so it may then be referenced by other models or deployed to a server. You simply open the Model Library, select your model, and press the Publish button to output your published model to the output folder specified in Window/Preferences/NexJ Studio/Build Settings.
Set current server Select the current environment (or server) for deployment and execution from your environments.
Set current connections Select the current set of connections (for example, databases or message queues) from your environments.
This is only used in conjunction with a .server file. If you are using a .environment file, the connections are already included there.
Set current user Select and manage the user context under which to run your tests and consoles.
Ensure that this setting is configured. If it is not, you will be running your local server without user privileges, potentially resulting in unexpected behavior.
Deploy model Publish and deploy your model into the current environment.
Validate model Validates the model and places any warnings or errors in the Problems view.
Run Console Starts a local, server, remote or client console for testing.
Run All Unit Tests Run or debug all unit tests. To run specific unit tests, use the Unit Test View available by selecting Window > Show View > Other and in the Show View dialog selecting the NexJ Studio > Unit Test menu item.
Run application Run any of the presentation applications on any of the client frameworks.
Debug current server Start debugging the currently running server.
To debug code in .layout files, add ?debug=1 to the browser URL. For example, if you normally access your application at http://localhost:7080/nexj/ui/portal, you need to use http://localhost:7080/nexj/ui/portal?debug=1 instead.
Run tool Provides access to various tools, including:
Cipher Tool - Encrypt passwords and master password server files.
Data Load Tool - Importing and export data to and from Object Representation to specific data sources.
Database Schema Tool - Generate data source specific SQL statements for creation, upgrades, inserts, and so on.
Generate BI Metadata - Generate BI metadata to support analytics and reporting.
Local Scheme Console - Run an in-process version of the local Scheme Console.
Strings Tool - Import and export string resources for internationalization.
Metadata Hotswap Hotswapping allows you to quickly test code changes without restarting your server. To hotswap your changes, press the "Metadata hotswap" button on NexJ Studio toolbar (or Alt + F5) when your local server is running. Refresh your browser to see your changes. Use the dropdown on the NexJ Studio toolbar to switch between "Reload UI" and "Reload All".
Reload UI
This option only swaps out MDA UI metadata, which includes layouts, portlets, and dialogs, ... This option takes less than 1 second and should be used in favor of "Reload All" when you're only making MDA UI changes. If you are changing raw AFL controls, hotswapping isn't needed to see your changes.
Reload All This option swaps all metadata, including MDA UI metadata, business model, and integration changes.
Tip
After hotswapping, your server console still uses the old metadata. Type(*repl*'reset)in the server console to pick up the model changes.
Close the Welcome Screen to begin working with NexJ Studio.
You can have multiple instances of NexJ Studio on your machine. You may put versions in different locations and run them at the same time as long as they are pointing to different workspaces.
Creating your databases
The model contains a the application's logical database structure. Our development environment also has the physical details of how to connect to and create this database. These details include settings for the server, security, database types (for example, Oracle or MS SQL), integration channels, and more. Environment files help manage settings for the different environments (for example, QA, Development, User Testing, and Production). For more information about environments, see Environment Files .
A bit of history
In some of the tooling, you are presented with a Server selection and a Connections selection, but end up selecting an Environment. Originally, a Server file managed information about the server (for example, security, clustering, LDAP) and a set of Connection files managed database and integration connections. This has been modernized and simplified and we now typically use an Environment file representing both the Server and Connections along with Properties files that may be selected for different purposes (for example, development, unit testing, and performance testing).
The bottom line is that you select an Environment/Properties file combination (for example, Development (Development.properties) in the Server dropdown and leave the Connections blank.
NexJ Studio has many tools to help with your development activities. Use the Database Schema Tool to generate SQL scripts for creating the Training and UnitTest databases.
As stated in the prerequisites, MS SQL Server must already be installed.
To create the database for our training development:
Select Run > Run Tool > Database Schema Tool. Use the following settings (should be the default):
The data path setting is dependent on your MS SQL settings and personal preferences. We recommend you retain the training default settings.
Click Run. In the Console view, you should see activity that ends with "Exit code = 0". In general, for all NexJ Studio tools, "Exit code = 0" indicates success. This generates a database creation script in your /training/out/sql folder called training_DefaultRelationalDatabase_setup.sql.
Open SQL Management Studio, and run the script. This creates your storage, index space, database users, and roles for your development database.
When you run the script, you should see:
After creating the database for our training development, create the unit test database. This database is used over and over to reload a fresh image before starting certain unit tests.
Re-run the Database Schema tool, selecting UnitTest.properties.
This overwrites training_DefaultRelationalDatabase_setup.sql with settings for your unit test database.
Run this in SQL Management Studio as well.
To test that everything worked:
Select your development environment with Project > Select Server > Development (Development.properties,test).
Click the Set Current Server icon in the toolbar to open the environment.
Navigate to the Data Source Connections tab at the bottom of the Environment Editor, and select Relational Database Connection.
Click the Test Connection button. You should get a Test connection successful response.
Loading the database
So far, we have created the empty databases. We can now use the Data Load Tool along with the logical database definition from the DefaultRelational.data source file to create all of the tables and indexes, and load them with appropriate sample data.
Select the Run > Run Tool > Data Load Tool.
Make sure you check the Test option in the Server and Connections section and set the Server property to Development.properties, the Command to recreate, and click Run. This creates the application's tables and indexes, and loads your database with sample data.
Again, an Exit code = 0 indicates success. You can now run an application in your local environment.
Select Run > Run Scheme Console > Server Console . When you see in your console output, your server is up and running.
To access the application, browse to http://localhost:7080/training/ui/portal and enter User: wm1, Password: nexj. You might want to bookmark this URL in your browser, as we will be using it frequently going forward. The following screenshot shows an example of the Home workspace that is using the training theme. For more information about themes, see UI themes and CSS.
Congratulations on getting your environment set up! You are now locally running a full Model Server loaded with the training model.
What is this "Potential Performance Problem"?
While loading the database, running unit tests, or just running your server, you may see output similar to the following:
; 17:58:02,939 WARN [SQLAdapter] (Thread-0) Retrieved 7323 instance(s) of EnumCode in 2803 ms (potential performance problem) nexj.core.util.StackTrace at nexj.core.persistence.GenericCursor.logDuration(GenericCursor.java:400) at nexj.core.persistence.GenericCursor.internalNext(GenericCursor.java:1347) at nexj.core.persistence.GenericCursor.next(GenericCursor.java:1447)
This is not really an exception. It is a warning that a query took longer than a preset time to execute. We are always looking for ways to improve performance, so use this approach to flag long running (usually > 1 second) queries for further investigation in the server log output. You can disregard these types of warnings during training.
Training environment
For training, we have pre-configured the NexJ Studio, Java, and Debug perspectives which are available at the top-right corner of the toolbar.
The NexJ Studio perspective is best when working with the tools and models. The Java perspective works well if you need direct access to the file system. The Debug perspective is helpful for understanding what is going on under the covers.
The file system starts with the install directory (
c:/nexj_studio/13.0-training
). This folder contains nexjstudio.exe and nexjstudio.ini. Underneath this is a bunch of eclipse folders and a folder called 'training' which contains folders called:
models (eclipse workspace), which contains subfolders for
training (a training model with standard subfolders such as env, meta, and mod)
and a number of react example projects
out (project output folder with standard subfolders such as deploy, publish, and sql)
databases (a location to create your databases)
server (where your deployed server will be installed in future lessons)
We have provided you with two environments: one for regular development, and one for running unit tests. You have already configured the database during the setup steps above. There is one Development.environment file as well as two properties files: Development.properties, and UnitTest.properties. You may inspect these files in the C:\nexj_studio\13.0-training\training\models\training\env folder if you are curious. They are ready to use for the upcoming lessons.
Run a unit test
Unit tests are important to the maintainability of your application.
Stop the Scheme Console by clicking the Terminate button .
Select the Unit Test tab in the Model Navigator view of NexJ Studio.
Right-click on the Account unit test and choose Run Selected . This initializes and loads your unit test database and runs the suite of tests for the application's Account functionality. This will take some time.
When complete, you should receive an Exit Code = 0 in the console and the Unit Test view should look similar to the following (if you expand the Account element):
If there was an error, the stack trace will be available at the bottom of the Unit Test view.
Congratulations! Next, review key NexJ Studio concepts in the Orientation topic.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.
at the top of the navigator. Items from base models or mixed-in models are displayed in the navigator as grey 
; mixed-in items have a little "m" on them 
; new items display in color 
; and customized items display with color and a strike symbol 
.
at the top of the navigator.
