Java App Dev Framework

Checking out a project

In eclipse, go to the SVN Repositories window and:

1. Go to idd-svn > projectyouwant > trunk
2. Right-click trunk and select Check out

You will then need to configure the project's local site settings:

1. Create a new directory called site under the project's top level
2. Copy the files in site-template into it
3. Edit site/ApplicationLocal.properties
   1. Change the authentication.user to your kerbname
   2. Set sf2_passwd value to your cert public key string:
      1. In your browser, go to https://mortar-dev-mit-edu.ezproxyberklee.flo.org/getcert.html
      2. Copy the text just after ----BEGINCERTIFICATE--- until you reach the last -----ENDCERTIFICATE----
      3. Paste this as the value for sf2_passwd (this is your cert public key)
   3. Change c:/dev in r3props to your workspace directory, e.g. c:/workspace/mortar/tools/GlobalResources.properties
4. Edit site/log4j.properties; Log4j will output to your eclipse console and to a file
   1. Change the F1.File property to point to where you want your log file to go

Project structure

Overview

Projects are "dynamic web app" eclipse projects.

They contain this structure:

...

src/

...

...

source

...

...

edu.mit.appname.controller.action

...

where struts actions go

...

...

edu.mit.appname.controller.data

...

where struts forms go

...

...

edu.mit.appname.dao

...

where database methods go (for projects that use hibernate)

...

...

edu.mit.appname.model

...

where biz objects go that are passed to the front end

...

...

edu.mit.appname.proxy

...

where generated rfc call and data objects go (for sap projects)

...

...

edu.mit.appname.service

...

where the methods the actions call to get backend data converted to the model go

...

...

conf

...

...

used on the server for deploying the app to OAS (ignore this directory)

...

WebContent/

...

...

front end

...

...

css

...

contains app_layout.css, etc

...

...

js

...

contains app_specific.js, etc

...

...

WEB-INF/classes

...

where ApplicationResources.properties goes, etc

...

site-template

...

...

a set of template files for your site dir

...

site

...

...

where your local machine specific properties files go, initially copied from site-template

...

...

ApplicationLocal.properties

...

where you place props local to your machine, see below

...

...

build.properties

...

where you put build info local to your machine

...

...

.

...

...

where you configure logging local to your machine

...

build.xml

...

...

used only on the server to build and deploy the app

In sap In SAP based apps, the service does most of the conversion between sap SAP objects (proxy) and biz objects, as opposed to hibernate Hibernate based apps where the conversion is done by hibernate Hibernate in the dao classes.

App specific css and js go in css/app_layout.css and js/app_specific.js.

...

Apps are normally setup so that eclipse will be able to build the app (with your local machine specific props) and deploy it to your local server.

The proxy classes

The proxy classes only exist for apps that talk to SAP. They are generated by sap2java from the RFCs you want to call in the app. See sap2java for how to generate proxies.

Proxy classes are sap data types and must be converted by the service class to real biz model classes.

The dao classes

The dao classes only exist for apps that talk to oracle thru hibernate. They are usually generated by hibernate.

Dao classes retrieve data from the database and convert it directly into biz model classes.

The service classes

There is normally only one service class per app. The service class' job is to get data from the back end and perform some biz logic on it and return it to the front end (actions). There should be one service interface and one class that implements it, e.g. OasSkeletonService, and OasSkeletonServiceImpl.

For SAP apps, the service calls RFCs and converts their proxy data into biz model objects. The service class should be a subclass of SAPServiceSupport which provides methods to call the back end and process errors.

For hibernate apps, the service calls the daos to get biz objects and performs whatever biz logic is necessary on them.

Spring config

The service spring beans are configured in applicationContext.xml (not in action-servlet.xml).

For SAP apps, there is a default applicationContext that sets up the proper service properties needed to connect to SAP. (There are also some extra property settings for doing mock services; see the file).

The service interface allows you to swap out implementations in the spring config so you can use a mock service instead for testing, etc.

The spring config for services also specifies where to get RFC messages from. Messages from the back end usually either come as a collection of messages from a table (e.g. ET_RETURN or ET_MESSAGES), or a single message stuffed into a field in the return output object. The SAPBaseAction and SAPServiceSupport classes automatically handle message processing so you don't have to. The only thing you need to do is configure what tables and/or properties the message/messages can be in based on what all its RFCs return. E.g.:

• If some of your RFCs return messages in the ET_MESSAGES table and some return them in ET_RETURN, you would add both of these to the spring config for the messageKeys property.
• If some of your RFCs return a single message in the output object, say in the field E_RETURN, then you would specify e_RETURN in the messageKeys.
  You should specify all the possible names that your RFCs return in the messageKeys property. Table names are usually all uppercase (these are just keys in a hash); however, output object field names must start with a lowercase letter (this is because the code calls the getter).

If the message objects returned from the back end have both the TYPE and MESSAGE fields, then setting messageKeys is all the configuration you need to do (these are automatically dealt with). However, if some other type of object is returned instead that doesn't have these fields, you will need to add code in the convertRFCMessage method in your service implementation to convert these message objects to the RFCMessage type.

The model classes

The model classes are business classes. These classes are not specific to any front end or back end, but model the business itself. So when you design them, they should not be designed around what a page requires (e.g. one object that contains a bunch of stuff for the whole page) or what the back end returns (e.g. direct map to proxies). They should be designed around the business model itself.

The controller classes

The controller classes are actions and forms. It's the action's job to take biz objects from the service and convert them (if necessary) for display on the screen, and take data from the jsp and convert it to biz objects to send to the service. An action should do only one thing, i.e. we aren't doing actions the "multiple method" way.

Forms should be request based unless they are carried across more than one page, e.g. as in a wizard. Most of the time, you should be able to stuff biz objects directly into a form (and not flatten them out; i.e. create fields in the form for each field in the biz object). Struts should be able to deal with populating and returning nested objects.

A form's job is data input. It should not be used for data output unless some of that data is used as input too (this does not mean dropdowns, etc). Output data should be stuffed into the request by using request.setAttribute. You can then access the data in the jsp using the c taglib. Any data that is required for more than one screen, e.g. dropdown data that doesn't change, etc, can be stored in the session.

For apps that use SAP, all your actions should be subclasses of SAPBaseAction. This provides automatic RFC error message handling (i.e. it takes all rfc messages and stores them into the struts actionmessages automatically). It will stop any time an rfc returns an error message. In the rare case you need to do something else (like continue other processing) when an rfc error message occurs, you can wrap a try catch on MessageRuntimeException around your service execute calls.

TBD - talk about how to go to different actions from the jsp using the hidden thingy

Spring config

The spring config for actions should be done in action-servlet.xml.

This file should contain a bean entry for every action in your app and they should be singletons. There is normally a base action class that is injected with the service all your actions will call. You can use mock services by overriding this.

Your app can have any number of entry points. Each of the entry points would have an action that can just be configured in spring to use the class edu.mit.mortar.controller.action.GlobalEntryAction. However, they must be named XXXEntryAction (where XXX is some name you choose), otherwise the session restart mechanism will cause your app to loop infinitely.

For SAP apps, your base action should be the class edu.mit.mortar.controller.action.SAPBaseAction (which is usually the default in the skeleton).

Struts config

The struts config should have some defaults setup for your app.

Your app can have multple entry points. Each of these should be like the EntryAction example provided.

For each action that accepts input from the user there should be a form attached to it, and a jsp/tile to go back to in case of errors should be specified as the input attribute (see SearchPeople for an example).

For actions that don't need input, they should not have a form.

Tiles config

Tiles config comes preconfigured with some building blocks for your pages.

Pages you create should extend sapweb.standard; see oasskeleton.enter_search_criteria for an example. You must specify a default pageAction that the page will go to.

JSPs (the front end)

You can usually base your jsps off one of the example pages, enter_search_criteria.jsp or search_results.jsp. There has been no choice made on whether we should use bean/logic tags or c tags, so that's up to you although c tags are easier to use.

TBD - this needs to be filled in more on insidemit css layout, js, etc.

TBD - talk about how to go to different actions from the jsp using the hidden thingy

TBD - talk about how to do ajax once Seth figures it out

Taglibs

Standard jstl and struts taglibs are in the app, including:

• c
• fmt
• html
• html-el
• logic
• logic-el
• bean
• bean-el
• tiles

In addition, some extra jakarta taglibs are included:

• string
• datetime

Application settings and messages

Application settings and messages are in the file ApplicationResources.properties.

This file should contain all the messages that the app will display.

It also contains a few other settings:

These need to be configured for each app:

• sap.proxy.pkg - is the name of the proxy package in your app; the sap2java library uses this property to know where your proxies are; e.g. edu.mit.vpis.proxy
• appname - this should be set to the name of your app, e.g. vpis
  These are standard:
• app.message.generic - this is a generic message that is used to output RFC messages
• errors.gateway - this message is output by IDDAction if you enter via a non EntryAction
• errors.required - not sure what this is...

Sap2Java

See sap2java.

Eclipse Project Structure

The following tree documents the Eclipse standard project structure.  Each section contains detail information on the specific project component. 

Checking Out an Eclipse Project

See the iJAG FAQ for instructions on checking out an Eclipse project.

Configuring a Struts 1.2/Spring Project

See the iJAG FAQ for instructions on configuring a Struts 1.2/Spring Project. 

Message Handling 

Message handling is configured in the Spring configuration for service objects.  See the applicationContext.xml section on Message Handling for information on how to configure default message handling and override message content.

Building and Running an Application in Eclipse

...

If you forget to create your site dir folder and configure it, your app will not build. This is a common problem. If mortar 00.xx or insidemit are not checked out and set up properly, your app will not build. See iJAG FAQ for instructions on deploying locally.

To run your app, just right click the project and select Run As > Run on Server. The first time you do this it will ask you to pick which server to run on. If you check the checkbox at the bottom it won't ask you this again. By default, it will go to the action EntryAction.do. If project(s) other than the one you've chosen to run are run also, it is because they were added to your server earlier. You can remove them from the server by going to the Servers window, expanding the Oracle server, selecting the project you wish to remove, right clicking and selecting Remove.

You can access your app in your web browser at http://localhost:8888/apps/yourappnamehere/ and it will automatically go to EntryAction. If you have more than one entry point you will need to specify which action XxxEngryAction to go to. For SAP apps, you do not need to specify sapSystemId as this is configured in your site/ApplicationLocal.properties file (the r3default property).

If you want to access your localhost from a different IP address, you will need to know the name. You can get this info by bringing up the Command Prompt and ping localhost. The response will be something like Pinging fss-115-2.mit.edu ... fss-115-2.mit.edu should replace loaclhost in the URL above.

When you rebuild your app, you can either do Run As again or you can right click your server and select Publish.

To debug your app, make sure you have some breakpoints set and then cause a rebuild to happen (you can do this by doing a Clean). Then restart your server in Debug mode. You can then either right click the project and select Debug As > Debug on Server, or publish the app and just go to your browser. When you reach a breakpoint, eclipse should switch to debug view and your browser will sit there waiting.

Demo

...

Application

The skeleton we use to create new apps comes with a built-in demo app. You should base your code on this. The source for the demo is in the edu.mit.oasskeleton package structure, and there are a couple jsps and struts configs, etc.

Junk

mortar - tbd

Logging - When you log an error make sure you include the person's kerbid if possible so we can track the error from the helpdesk easier.
TBD - how to turn on debug logging, etc (e.g. edu.mit.xxx.controller.action=DEBUG, what to name your jsp loggers, jsp.yourapp.jspname)

...

It also implements a search help.

Search Help

The documentation for implementing search help using mortar 4.1x or later is in the search help tag library (searchhelp.tld). The original version of this tag library is maintained in the skeleton, oas-skeleton.

JSP (with Search Icon)

The JSP with the search icon Image Added will pass mortar a key and one or more field names. You can get the key and field names from the ABAP developer.

Example (taken with slight variations from the safo project) 

Image Added

Most of the time the ABAP developer will need to add code to the RFC, Z_CA_SEARCH_HELP, to implement the specific search help that is needed. This RFC is expecting:

• a key to be passed from the JSP  
• the field names that are going to be searched.

The first two or three characters of the key represent the business area: EHS, FI, HR, MM (materials management - Logistics Team). Ask the ABAP developer for the key and the field names.

Examples of keys and their field names:

• FI_SAFO_COST_OBJECT
  • KSTRG
  • TEXT
• EHS_LIST_PERSON_BY_NAME
  • LAST
  • FIRST
• HR_COST_OBJECT
  • KSTRG
  • TEXT

 ABAP developers should use English for our keys & field names but we sometimes slip up and use the German abbreviations. KSTRG is the German abbreviation for Cost Object.

In addition to what is passed to the RFC, the JSP also needs to code the columns that are returned from the RFC. 

The sample JSP code: 

Image Added

• form is the project's controller > data > actionForm (ReportRequestForm) associated with the JSP with the magnifying glass icon Image Added.
• origaction is the project's controller > action > action (/RequestReport.do) that launched the JSP with the magnifying glass icon Image Added.
• key is the key (FI_SAFO_COST_OBJECT) you get from the ABAP developer.
• interactive ("y") indicates whether there are so many potential search results that you should first request search criteria ("y") If there are 50 or under no search criteria are necessary and mortar will take the end user directly to the search results ("n"). (? - Ask your UI person but generally if there are a max of 15 search result rows interactive should be "n".
• title is what will appear (Cost Objects Title) after "Search for " on the search help criteria page.
• incrit crit are the names (KSTRG & TEXT) you get from the ABAP developer.
• incrit label are the labels (Input Cost Object & Input Description) for these names that will appear on the search help criteria page.
• incrit vfield are the actionForm field names (co & coDesc) that correspond to these names & labels.
• dispfield field are optional tags used to specify which columns will be displayed in the search results. If specified these columns must be the same names as the metadata column headings returned by the RFC. The ABAP developer can supply the names of these columns.
• outfield rfield are used to map the columns to the actionForm field names. These must be the same names as the metadata column headings returned by the RFC. The ABAP developer can supply the names of these columns.
• outfield dfield are the actionForm field names (co & coDesc) corresponding  to the results columns.
  Image Added
  Beyond having the ABAP developer modify Z_CA_SEARCH_HELP to incorporate your specific search help and making these changes to your JSP, there is nothing else that needs to be done to implement search help for any project that has been created using oas-skeleton and mortar 4.2x or higher 

Revision History

(latest on top)