Joty Workstation application guide

Setup and deployment of the application

A preliminary task needed to both of the Joty running modes is the creation of the database instance that is performed by executing the script, designed together with the application itself, on the target dbms.

As desktop / client-server application

From the Java Applicaton project a jar file must be generated, as 'runnable'. If the report features are used in the implemented application then the application jar must be generated with the BIRT Report engine library included in the class path and depending on the way chosen, then, that library will have to be addressable from the final location for the jar. Once the installation folder has been chosen, a copy of the joty.xml file must be customized at least with:

• the Url of the database
• the jdbc driver class name
• application icons file names
• the correct database name in the 'dbmsUserGrantedRolesStmnt' item
• the correct expression in the 'dbmsSessionPreset' item
• the 'dbManagerClass' item with the full class name of the implemented class
• if the Accessor mode was used in the implementation of the application then the full class name of the implementation of the application Accessor
• the languages provided as semicolon separated list (with trailing semicolon on the last occurrence) in the 'languages' item
• a value (true/false) for the 'addRemoveUsers' configuration item

the configuration file must be placed in the installation folder, indeed, together with:

• the 'lang' directory containing one directory for each language mentioned in the configuration file, named as the literal used there and containing the following files:
  • 'JotyLang.xml' conveniently prepared if the language is not provided by the current distribution of the framework, it can be derived by translation of the items into the target language
  • 'AppLang.xml' conveniently prepared since it contains all the application-specific language literals resolutions
• if the report features are used by the application, the report design directory named as mentioned in the configuration file (default is 'reportDesigns'), containing all the .design files, as projects files of the reports.

As web application

From the Java Applicaton project a jar file must be generated, as 'runnable', but, if the 'Accessor' mode was used in the implementation of the application and the choice is for remote location for the Accessor instance, then the jar file must not include the application package containing the Accessor implementation class.

Then the file must be signed with the signatures of the developing entity (mainly because the Java Web Start technology requires this).

After that, the file must be placed in the web content path of a Dynamic web project settled just for building the server instance and in this path must also be placed the following objects:

• a copy of the JotyServer.xml file customized at least with:
  • the Url of the database
  • the correct expression in the 'dbmsSessionPreset' item
  • if the Accessor mode was used in the implementation of the application then the full class name of the implementation of the application Accessor
• a copy of the ServerSideJoty.xml file customized at least with:
  • the jdbc driver class name
  • application icons file names
  • the correct database name in the 'dbmsUserGrantedRolesStmnt' item
  • a value for the 'dataSourceName' configuration item
  • a value (true/false) for the 'addRemoveUsers' configuration item
  • the languages provided as semicolon separated list (with trailing semicolon on the last occurrence) in the 'languages' item
  • the 'dbManagerClass' item with the full class name of the implemented class
• a 'lang' directory just as that one of the case of Desktop / client-server scenario
• the same is for the report design directory a part from that it must be put, first, in a directory named 'JotyServerReports'.
• a copy of the .jnlp file where all the attribute values must be conveniently set
• an html page containing an anchor tag having as href attribute value the following expression:

  "javascript:deployJava.launchWebStartApplication('[jnlp file name].jnlp');"

  where the correct name of the .jnlp file must be specified.

Then, the directory 'WEB-INF/lib' must be filled with the following .jar files part of the framework binaries:

• org.joty.server.jar
• org.joty.basicAccessor.jar
• org.joty.common.jar

and with the application-specific jar files that must be present on the server side - typically:<>

• a jar file containing an application implementation of the org.joty.common.DbManager class
• if the accessor mode was used in the implementation of th application, the jar file containing an application implementation of the org.joty.basicAccessor.BasicAccessor class

Furthermore, if the Reporting features was used in the implementation of the application, the BIRT Report Engine library must be in the class path of the project.

Lastly, the 'META-INF/context.xml' file must be customized on the following attributes:

• driverClassName
• url
• name
• username
• password

The war file, indeed, can be exported and put in the Tomcat 'webapps' directory.

before starting the application two aspects must be verified on the Tomcat server:

• the availability of the jdbc driver
• the accessibility of the BIRT Report Engine library

Startup of the application

In web mode the application must be started by clicking on the link of the main page addressed with the web browser at the application Url. This will trigger the Java Web Start technology that will take care of various step related to the verification of the Java workstation environment until the application is downloaded and, indeed, the web server certificate is verified or negotiated (through ssl) and the user is presented with the login dialog.

In desktop / client-server mode, instead, it is enough to get the execution of the application jar, located in the file system, in the installation folder of the workstation. The execution is typically obtained (it depends on the O.S. platform) by double clicking the file. So that the login dialog appears to the user.

User and password must be submitted to the system, indeed;

Joty Workstation application built-in features

Here is the list of the aspects the user of the Joty Workstation application can perceive:

• Roles panel for the visualization of the application specific roles, allowed only to Administrators role
• Authorization and user profile management that through the built-in menu provide special handling of the Administrators role, (the one having ID = 1 in the roles table), as it is shown below.

  The menu Authorization offers three items:

  • Change password enabled for all the users
  • Roles panel for the visualization of the application specific roles, allowed only to Administrators role
  • Users panel for the management of the user accounts of the application: it behaves as follows:
    • Only users owning the Administrators role are allowed to access it
    • Depending on the value of the 'addRemoveUsers' configuration item the administrator can add or remove user accounts
    • In shared mode (the mode for public demonstration purposes) all the users owning the Administrators role don't appear in the list of users after their creation, that is, they cannot be managed - If a user acquires the Administrators role he/she cannot loose it anymore unless a database intervention is made in the dedicated table.
    • 'admin' user never appears in the user list, in any mode
• The look-and-feel of the generic data access form presents a button set shown in the following table with respective semantics, in idle mode:

  Button	Semantics
  	New record (enters the 'Editing mode')
  	Edit record (enters the 'Editing mode')
  	Delete record
  	Next record
  	Previous record
  	Recall the main frame window
  	Quit the form

• ... when in editing mode:

  	Save record (quits the 'Editing mode')
  	Cancel (discards any change made on the record or abandons the creation of the record if it is a new one - quits the 'Editing mode')

• The look-and-feel of the buttons for confirming or canceling a choice in a dialog:

  	Ok
  	Cancel

• The look-and-feel of the icons that identify the semantics type in the messages to the user:

  Icon	Semantics type of the message
  	Warning message
  	Information message
  	Question message
  	Message that asks for a user input

• The mouse pointer that appears when a "drag" suggests the possibility of deletion of the entity 'being dragged' (by dropping it):

• The look-and-feel of the generic form that performs the access to the data of the application: a part from its decoration that depends on the operating system (Msc Os X, Linux Gnome, Linux KDE or Windows) the internal structure is specific to the Joty framework:

  • The set of buttons for editing
  • The optional presence of a searcher panel on the left or on the top of the form
  • The presence of different sheets for accessing different subset of data in respect of the current record of the main entity
  • Each sheet (panel), then, may have a grid that allows record navigation by the selection of the rows.
• The behavior of the main frame that, just a data access dialog is opened, becomes a small floating window, "always on top", containing the application menu (this happens in Linux and Windows OSs since in Mac OS X the menu is transferred on the Mac application menu).

• The availability of the 'View' menu that:
  
  • allows the change of the status of the main frame
  • enables the tool-tips on most of the objects provided by the framework
  • allows the change of the font size on the application on 'this' workstation (only administrators users)


• The availability of the 'Tools' menu:
  
  that provides the selection of the language among those ones prepared and, only to administrators users, the specification of the location in the 'Application settings' dialog.

• The availability and the look-and-feel of the blob component and of the image component. They are dedicated to the access to binary objects stored in the database. The latter is enriched by an almost squared preview area where a double click causes the opening of the built-in viewer.

  These two components perform the editing of the binary content in an independent way from the usual editing session, such that they are equipped with dedicated commands that work just when the general editing mode is switched off.

  They are equipped, indeed, with the following commands:

  Button	Semantics of the command
  	Opens the document with an external application associated or with the built-in image viewer in the case of image component
  	Downloads the current object or all the instances corresponding with the associated database table field
  	Deletes the binary object
  	Uploads the binary object by browsing the file system

• The built-in calendar recallable double clicking the content of a date o date-time text box.
• Frequently available, the opening of a detail data dialog by double clicking on a row or on the empty area of a details data grid (it depends on the choices of the developer: whether he/she uses inherent features of the framework)
• The usability of the built-in image viewer that:
  • allows opening an instance by double clicking on any image preview present in a data grid
  • allows zooming and dragging of the image content
  • allows the disposition of the instances, opened on the same database field, as tiles or as a stack
• The 'Windows' menu the acts on the opened windows
• The reaction of the framework when an editing session started in a form is forced to be interrupted by an external event or action on another form that implies the closing of the first one: the framework manages the conclusion or prosecution of the session blocking the pretending context, all under the choice got from the user.
• The two different modes by which a searcher, either stand-alone or integrated in a data access form, behaves:
  • explicit search command: the search button is visible and the framework waits for its explicit use by the user
  • implicit search command: just a character is typed in a text box or a selection is performed in a combo-box within the search criteria panel, the framework invokes the research.
  After that, pagination of data searched is performed, basing of the size expressed in the 'pageSize' configuration item.
• The consistence of the enabling state relative to form fields and commands, to searcher fields and commands, depending on the current state of the form, the editing session management on the various sheets contained, when the user switch among them, are all aspects performed by the framework.
• The navigator-editor list dialog (actually built by a NavigatorEditorPanel object), that, instead of performing an usual editing management, providing commands at the bottom of the dialog, allows direct access to the database field through the columns of the main grid, made contextually editable and notifying themselves by coherent tool-tips.
• The choice of the rendering format for any printable document generated by the application, document or report it could be (this descends directly from the use of the BIRT technology) with the memory of the last format used.

• The possible availability of a 'Show record / Hide record' button at the bound of a data dialog, when the dialog is equipped by either a searcher or the data management area and is opened as selector.