Eclipse Project Structure

Projects are "dynamic web app" eclipse projects. They contain this structure:

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.

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.

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)