Overview

Projects are "dynamic web app" eclipse projects.
In SAP based apps, the service does most of the conversion between SAP objects (proxy) and biz objects, as opposed to Hibernate based apps where the conversion is done by Hibernate in the dao classes.

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

ApplicationResources.properties contains all the props specific to the app itself no matter what machine it runs on. Usually, all messages and displayable strings go here.

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.

Eclipse Project Structure

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

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.

Building and running an app

If you forget to create your site dir and configure it, your app will not build. This is a common problem.

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.

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 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).

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 app

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)

Unit testing using junit - tbd

Revision History

(latest on top)