Class next.wo.WebApplication

CLASS DESCRIPTION

Extends:
next.util.NextObject

CLASS AT A GLANCE

Purpose

A WebApplication object receives an HTTP request from an adaptor, manages the request-response loop that processes the request, and returns a response to the adaptor. It also manages sessions, caches component definitions and page instances, and offers localization, debugging, and error-handling support.

Principal Attributes

Creation

Created in default application main (WODefaultMain)
WebApplication()

Commonly Used Methods

pageWithName Returns a Component (page) instance identified by name.
awakeAllows custom application initializations during the start of a request-response cycle.
takeValuesFromRequest
invokeAction
appendToResponse
These three methods allow custom application logic during the value-extraction, action-invocation, and HTML-generation phases of the request-reponse loop.
setTimeOut Sets the period of inactivity after which the application process stops executing.
setPageCacheSize Sets the number of page instances cached in the session by the application.
setCachingEnabledControls whether the application caches component definitions.



CLASS DESCRIPTION

The primary role of the WebApplication class is to coordinate the handling of HTTP requests. Each application must have exactly one WebApplication object (or, simply, application object). The application object receives client requests from an HTTP server adaptor, manages the processing that generates a response, and returns that response--typically an object representing a web page--to the adaptor. The adaptor, in turn, forwards the response in a suitable form to the HTTP server that originated the request.

In handling requests, an application object creates and manages one or more sessions; a session (represented by a WebSession object) dedicates resources to a period of access by a single user and stores persistent state during that period. Conceptually, each cycle of the request-response loop (or transaction) takes place within a session.

Besides acting as a facilitator between the adaptor and the rest of the application during request handling, WebApplication performs many secondary functions. It returns pages based on component name, caches page instances and component definitions, provides some facilities for error handling and script debugging, and furnishes a variety of data, such as the base URL and the current Context object.

Typical deployment schemes balance the processing load by having multiple application instances per server adaptor. A single application, in turn, can interact with multiple adaptors; for example, an application can simultaneously communicate with secure-socket and Distributed Object adaptors as well as HTTP adaptors.

You can instantiate ready-made application objects from the WebApplication class or you can obtain the application object from a custom subclass of WebApplication. Custom WebApplication subclasses are common in WebObjects applications since there is often a need to override the awake, sleep, init, and request-handling methods. Compiled WebApplication subclasses can take any name, but if the name is anything other than "Application" you must implement your own main function to instantiate the application object from this class. However, if the class name is "Application," you don't need to modify main. In scripted applications, the code in the Application.wos file becomes the implementation logic of a WebApplication subclass automatically created at run time; the application object is instantiated from this subclass.

The Application Run Loop

When a WebObjects application is launched from the command line, either manually or automatically ("autostarting"), the main function is called. In main the WebApplication subclass for the application is loaded. This class sets up for request handling by:

  1. Parsing the command-line arguments
  2. Creating and initializing an application instance
  3. Instantiating the adaptors with which the application will communicate

The application instance then has its run method invoked; in this method it registers its adaptors to receive run-loop events and then starts a run loop. The application remains in this run loop until it either times out, receives a terminate message, or has its process externally stopped.

The events that initiate each cycle of the run loop are not, as in a typical non-web application, user actions such as mouse clicks or key presses. Instead they are HTTP requests originating from client browsers. A browser sends an HTTP request (according to the URL specified) to an HTTP server, which then "talks" with a WebObjects adaptor customized for that server. The adaptor packages the request in a Request object and invokes the application object's handleRequest method. The receipt of this message initiates a cycle of the request-response loop, a three-phase cycle that handles the request and returns (in most cases) a response in the form of a Web page. Each phase of the cycle centers around a message propagated from the application object to all other "interested" objects in the application:

For more on the request-response loop, see the WebObjects Developers Guide. For information on valid command-line arguments for launching an application, see the "Manually Starting WebObjects Applications" section of the Serving WebObjects document.

Caching Strategies

The WebApplication object implements or controls three kinds of caching. You turn caching off or on in each case for reasons ranging from performance enhancement to page integrity or ease of debugging.

Component-definition caching
Component definitions are compact programmatic descriptions of components (pages or subcomponents), and are used to create instances of those components. When a page of an application is requested the first time, an application parses the HTML, declaration (".wod"), and implementation files in the component directory (".wo"), creates an internal representation of the component (the component definition), and instantiates the Component object from it. If caching is enabled, it stores the component definition in memory. If not, the application must reparse the files in the component directory every time that page is revisited.

You turn component-definition caching off and on with the setCachingEnabled method. By default, it is disabled. The advantage of having this kind of caching disabled is that you can edit a scripted component without having to relaunch the application every time to check the results. However, you should always enable component-definition caching when you deploy an application since performance improves significantly when you do. You can also control caching of individual component definitions using an identically named Component method. Selective caching is an especially valuable technique for very large applications where only the most common components and pages should be cached.

Page-instance caching
In normal processing of requests, an application caches at least one page instance. It does this because the lifecycle of a page overlaps transaction boundaries: a page "begins" by having its HTML generated and "ends" when the user navigates to a new page, which replaces the previous page in the browser. Because the application caches the page instance that once represented the response page, it can easily make it the request page for the next transaction.

Page-instance caching also facilitates backtracking in the client browser. It works like this: At the end of a request-response cycle, the application object stores the Component instance representing the response page in the session. When the user backtracks to this page, the instance is restored from the session object, enabling the page to display things as they were when the user visited it the previous time. By default, page-instance caching is enabled, with a cache limit of 30 pages.

You turn page-instance caching off by sending setPageCacheSize to the application object with an argument of zero. In this case, when the user backtracks to a page, the page is not stored in the session and so must be re-created "from scratch"; it will show none of its previous state. This situation is sometimes what is appropriate for certain applications. If you wish, you can also turn this feature off and implement your own selective page-caching scheme. Because page storage uses up application memory, you should test for the optimum cache size before you deploy an application with page-instance caching turned on.

Client caching
Usually client browsers cache pages (as HTML code) so they can redisplay them when users backtrack to them. You can turn off client caching by setting the date and the expiration time in the response page's headers to the current date and time. The client, however, retains the URL for the page. When the user backtracks to the page, the client resends the URL to the server, which returns a page based on a restored component instance.

WebObjects turns off client caching for you when you send the application object setPageRefreshOnBacktrackEnabled with an argument of true. This setting is valuable when you do not want the client to backtrack to a page that would be obsolete because of changes that might occur in the session. In particular, if you are using DisplayGroup's batch and selection-management functionality, you should turn off client caching.



Localization

Localization in WebObjects depends on an array of languages stored (as String objects) in the WebSession object using WebSession's setLanguages. The order of languages in the array indicates the preferred order. The language names in the array should map to "Language.lproj" subdirectories of the ".woa" directory. Thus, if there is a "French" item in the array, there should be a French.lproj subdirectory. The ".lproj" directories should contain everything that has localized content: ".strings" tables, sounds, images, and so on. Because the application first looks for resources in localized ".lproj" directories and then in a non-localized location, be sure there are no files of the same name in localized locations when no localization is supposed to occur.

The ".strings" file contains a simple property list that maps common keys to words, phrases, or sentences in a particular language. For instance, a Session.strings file in English.lproj might have the following content:

{

    buttonTitle = "Submit your request";

}


The Session.strings file in French.lproj would have the following:

{

    buttonTitle = "Soumettez votre requete";

}

You might want to have localized versions of a component's HTML file as well. If you do this, you must place the file inside of an ".lproj" directory in the component. For example, you would have this directory structure:

	English.lproj/
		MyApplicationWide.strings
	French.lproj/
		MyApplicationWide.strings
	Main.wo/
		English.lproj/
			Main.html
		French.lproj
			Main.html


Note: You can determine the language of the request sender by getting the value of the Request object's "accept-language" header. This returns a two-character value ("en", "fr", and so on) that you can then map to the language subdirectory.


Error Handling and Debugging

WebApplication offers developers some assistance in the areas of debugging and error handling.


CONSTRUCTORS

WebApplication

public WebApplication()

Initializes and returns a WebApplication object.This constructor initializes application attributes, and initializes the adaptor or adaptors specified on the command line. If no adaptor is specified, DefaultAdaptor is made the default adaptor. Some of the more interesting attribute initializations are:

A exception is thrown if initialization does not succeed.


METHODS

activeSessionsCount

public int activeSessionsCount()

Returns the number of sessions that are currently active. (A session is active if it has not yet timed out.)

The number returned here is only accurate if the application stores state in memory in the server, which is the default. If you use a custom state-storage strategy, there may be no way to tell how many sessions are active for a given application instance.

See Also: minimumActiveSessionsCount, setMinimumActiveSessionsCount


adaptorWithName

public next.wo.Adaptor adaptorWithName(java.lang.String aName, next.util.ImmutableVector someArguments)

Invoked in the constructor to create an adaptor. If you subclass Adaptor, you specify the Adaptor subclass you want the application to use with the -a option on the application's command line. When WebApplication encounters the -a option, it invokes this method. This method looks for a subclass of Adaptor with the name aName (which was supplied as the -a option's argument), and if such a class exists, a new instance is created. The someArguments array is populated with any adaptor-specific options (such as -p or -q) that follow the adaptor name on the command line. See the Adaptor class for more information.

See Also: adaptors


adaptors

public next.util.ImmutableVector adaptors()

Returns the current list of application adaptors. A WebApplication can have multiple adaptors. (To associate the WebApplication with multiple adaptors, you specify each adaptor on the application's command line using the -a option.) This allows you to design an application that can not only listen to a socket for incoming HTTP requests (using the DefaultAdaptor), but can also receive remote request messages using more advanced RPC mechanisms such as DO, CORBA, and DCOM.


appendToResponse

public void appendToResponse(next.wo.Response aResponse, next.wo.Context aContext)

The WebApplication object sends this message to itself to initiate the last phase of request handling. This occurs right after the invokeAction method has completed, typically with the return a response page. In the append-to-response phase, the application objects (particularly the response component itself) generate the HTML content of the page. WebApplication's default implementation of this method forwards the message to the session object.

See Also: invokeAction, takeValuesFromRequest


application

public static next.wo.WebApplication application()

Returns the WebApplication object for the current application. Since this is a class method, it can be invoked from anywhere in an application:

    WebApplication app = WebApplication.application()

This method is similar in purpose to WOApp, the global application object in the Objective-C version of WebObjects. It may not be overridden.

See Also: session, context


awake

public void awake()

Invoked at the beginning of each cycle of the request-response loop, affording the opportunity to perform initializations with application-wide scope. Since the default implementation does nothing, overridden implementations do not have to call super().

See Also: sleep


baseURL

public java.lang.String baseURL()

Returns the application URL relative to the server's document root, for example: /WebObjects/MyApp.woa.

See Also: name, path


context

public next.wo.Context context()

Returns the application's current Context object. May not be overridden.

See Also: Context class, application, session


createSession

public next.wo.WebSession createSession()

Creates and returns a WebSession object to manage a session for the application. The method goes through several steps to locate the class to use for instantiating this object:

  1. First it looks for a compiled class of name "Session" that is a subclass of WebSession.

  2. If such a class does not exist, it looks for a ".wos" script with the name of "Session" in the application wrapper (".woa" directory).

  3. If the Session.wos script exists, the method parses the script and dynamically adds a scripted-class subclass of WebSession to the runtime.

The method then returns an allocated and initialized (using the default WebSession constructor) session instance of the selected class. It throws an exception if it is unable to create a new session.

Note: An implication of the foregoing description is that the names of compiled WebSession subclasses should be "Session"; if not, you will have to override this method to use the proper class to create the session object.

See Also: restoreSession, saveSession


dynamicElementWithName

public next.wo.DynamicElement dynamicElementWithName(java.lang.String aName, next.util.ImmutableHashtable someAssociations, next.wo.Element anElement)

Creates and returns a DynamicElement object based on the element's name, a dictionary of associations, and a template of elements. This method is invoked automatically to provide a DynamicElement object that represents a WEBOBJECT element in the HTML template. You don't ordinarily invoke dynamicElementWithName, but you might override it to substitute your own DynamicElement or reusable component for one of the built-in DynamicElements.

The arguments aName and someAssociations are derived from a corresponding line in the declarations file. aName is a String that identifies the kind of element to create. Generally aName specifies a built-in DynamicElement such as WOString, but it may also identify a reusable component. (For more information, see the chapter "Using Reusable Components" in the WebObjects Developer's Guide.) For example, in the dynamicElementWithName message for the following declaration:

APP_STRING: WOString {value = applicationString;};

aName contains the string "WOString".

The someAssociations dictionary contains an entry for each attribute specified in the corresponding declaration. For the declaration above, someAssociations contains a single entry for WOString's value attribute. The keys of someAssociations are the attribute names and the values are Association objects.

WebApplication's implementation of dynamicElementWithName first searches for a DynamicElement named aName. If a DynamicElement is found, the method creates an instance and returns it. Otherwise, it searches for a component--either scripted or compiled--to return instead. If neither are found, this method returns null.


handleException

public next.wo.Response handleException(java.lang.Throwable aThrowable)

Invoked when an exception occurs within the request-response loop. The default behavior displays a page with debugging information. You can override this method to catch exceptions and display a "friendlier" error page.

See Also: handlePageRestorationError, handleSessionCreationError, handleSessionRestorationError


handlePageRestorationError

public next.wo.Response handlePageRestorationError()

Called when a page (Component) instance cannot be restored, which typically happens when a user backtracks too far. Specifically, this method is invoked when the following occurs: the request is not the first of a session, page restoration by context ID fails, and page re-creation is disabled. The default behavior displays a page with debugging information. You can override this method to display a "friendlier" error page.

See Also: handleException, handleSessionCreationError, handleSessionRestorationError


handleRequest

public next.wo.Response handleRequest(next.wo.Request aRequest)

Prepares for and manages the handling of a request. The method creates the Response and Context objects used in the request-response loop and causes awake and sleep to be sent to application objects at the appropriate times. This method is invoked by the HTTP server adaptor.


handleSessionCreationError

public next.wo.Response handleSessionCreationError()

Called when a session (WebSession) instance cannot be created. The default behavior displays a page with debugging information. You can override this method to display a "friendlier" error page.

See Also: handleException, handlePageRestorationError, handleSessionRestorationError


handleSessionRestorationError

public next.wo.Response handleSessionRestorationError()

Called when a session (WebSession) instance cannot be restored, which typically happens when the session times out. The default behavior displays a page with debugging information. You can override this method to display a "friendlier" error page.

See Also: handleException, handlePageRestorationError, handleSessionCreationError


invokeAction

public next.wo.Element invokeAction(next.wo.Request aRequest, next.wo.Context aContext)

The WebApplication object sends this message to itself to initiate the middle phase of request handling. In this phase, the message is propagated through the objects of the application until the dynamic element that has received the user action (for instance, a click on a button) responds to the message by triggering the method in the request component that is bound to the action. This phase occurs right after the takeValuesFromRequest method has completed. The default WebApplication implementation of this method forwards the message to the session object.

See Also: appendToResponse, takeValuesFromRequest


isBrowserLaunchingEnabled

public boolean isBrowserLaunchingEnabled()

Returns true if starting up the application also launches a web browser, and false otherwise. Browser launching is enabled by default as long as there is a WOAdaptorURL key in the file NeXT_ROOT/NextLibrary/WOAdaptors/Configuration/WebServerConfig.plist.

See Also: setBrowserLaunchingEnabled


isCachingEnabled

public boolean isCachingEnabled()

Returns whether component-definition caching is enabled. The default is false.

See Also: setCachingEnabled


isPageRefreshOnBacktrackEnabled

public boolean isPageRefreshOnBacktrackEnabled()

Returns whether caching of pages is disabled in the client. If so, the client does not restore request pages from its cache but re-creates them "from scratch" by resending the URL to the server. This flag is set to false by default.

See Also: setPageRefreshOnBacktrackEnabled


isRefusingNewSessions

public boolean isRefusingNewSessions()

Returns true if the application instance is refusing new sessions, and false otherwise. When the application instance refuses new sessions, the WebObjects adaptor tries to start the session in another instance of the same application. If no other instance is running and accepting new sessions, the user receives an error message.

See Also: activeSessionsCount, minimumActiveSessionsCount, refuseNewSessions


isTerminating

public boolean isTerminating()

Returns whether the application will terminate at the end of the current request-response loop.

See Also: setTimeOut, terminate, terminateAfterTimeInterval, timeOut


logString

public static void logString(java.lang.String aString)

Prints a message to the standard error device (stderr). The message can include formatted variable data using String's concatenation feature, for example:

    int i = 500;

    float f = 2.045;

    WebApplication.logString("Amount = " + i + ", Rate = " + f ", Total = " + i*f);

Note that logString is a static (class) method, so it can be invoked anywhere in a program, even if no reference to the application object is available. Also note that the equivalent method in Objective-C is logWithFormat:.


logToMonitorString

public void logToMonitorString(java.lang.String aString)

Same as logString but prints the string to the Monitor application's standard error. That is, the message is displayed in the command-shell window that was used to launch the Monitor application.

You use this method to log messages about significant events when the application is ready to be deployed and you will use Monitor regularly to monitor the application. Otherwise, use logString. If the Monitor application is not running or if this application instance is not being monitored, this method does nothing.


minimumActiveSessionsCount

public int minimumActiveSessionsCount()

Returns the minimum number of active sessions allowed. If the number of active sessions is less than or equal to this number and isRefusingNewSessions is true, the application instance terminates. The default is 0.

See Also: activeSessionsCount, refuseNewSessions, setMinimumActiveSessionsCount


monitoringEnabled

public boolean monitoringEnabled()

Returns true if the application is "monitorable" by the Monitor application, and false otherwise. An application is "monitorable" if it was able to find a running Monitor upon startup and it is able to successfully communicate with that Monitor.

By default, all applications are monitorable if the Monitor application is running on the same machine as the application. You can specifically disable monitoring using the -m OFF option on the application command line. If you want the application to be monitorable and the Monitor is running on another host, you can start up the application through Monitor, or you can specify Monitor's host on the application command line this way:

MyApp.exe -m ON -mhost monitorHost ...

See Also: logToMonitorString, the online document Serving WebObjects


name

public java.lang.String name()

Returns the name of the application, which includes all directories under DOCUMENT_ROOT/WebObjects and is minus the ".woa" extension; for example "HelloWorldJava" is a typical application name.

See Also: baseURL, path


number

public java.lang.String number()

Returns the application's instance number. If this application instance was started through the Monitor application or if the instance number was explicitly specified on the command line (using the adaptor's -n option), that number is returned by this method. Otherwise, the application's instance number is undefined, and this method sends the message applicationNumber to the current Request object to see if it has been assigned an instance number by the request.


pageCacheSize

public int pageCacheSize()

Returns the size of the internal cache for page instances. The default size is 30 instances.

See Also: setPageCacheSize


pageWithName

public next.wo.Component pageWithName(java.lang.String aString)

Returns a new page instance (a Component object) identified by aName. If aName is null, the "Main" component is assumed. If the method cannot create a valid page instance, it throws an exception.

See Also: restorePageForContextID, savePage


path

public java.lang.String path()

Returns the file-system path of the application, which is an absolute path and includes the ".woa" extension; for example "C:\NeXT\NextLibrary\WOApps\MyApp.woa" is a typical application path.

See Also: baseURL, name


pathForResource

public java.lang.String pathForResource(java.lang.String aString, java.lang.String aString)

Returns the absolute path to the application resource having the name of aName and an extension of aType. The method searches all localized application ".lproj" directories before searching directly under the ".woa" wrapper.

This method is provided for backwards compatibility only. For WebObjects 3.5 and above, you should use the ResourceManager API to retrieve resources.

See Also: stringForKeyInTable


printsHTMLParserDiagnostics

public boolean printsHTMLParserDiagnostics()

Returns whether the HTML parser prints warning messages to the standard output device (stdout) if it encounters unbalanced container elements or other syntactically incorrect HTML.

See Also: setPrintsHTMLParserDiagnostics


refuseNewSessions

public void refuseNewSessions(boolean flag)

Controls whether this application instance will create a session when it receives an HTTP request from a new user. If flag is true, the application does not create new sessions; when it receives a request from a new user, it refuses that request, and the adaptor must try to find another application instance that can process the request. If flag is false, the application creates new sessions. false is the default.

You use this method with setMinimumActiveSessionsCount to gracefully shut down application instances. Use setMinimumActiveSessionsCount to set the active session minimum to a certain number. When number of active sessions reaches the number you set and isRefusingNewSessions returns true, the application terminates.

See Also: activeSessionsCount, isRefusingNewSessions, minimumActiveSessionsCount, setMinimumActiveSessionsCount


resourceManager

public next.wo.ResourceManager resourceManager()

Returns the ResourceManager object that the application uses to manage resources.

See Also: setResourceManager


restorePageForContextID

public next.wo.Component restorePageForContextID(java.lang.String aString)

Returns a page instance stored the session page cache. The key to the stored instance is the its context ID, which derives from the transaction's Context or Request objects. This method returns null if restoration is impossible.

See Also: savePage


restoreSession

public next.wo.WebSession restoreSession()

Restores the WebSession object representing a session. In normal request handling, this method is called at the start of a cycle of the request-response loop. The default implementation simply invokes SessionStore's restoreSession method, but throws an exception if the SessionStore object is missing.

See Also: createSession, saveSession,


run

public void run()

Runs the application in a near-indefinite run loop in the default run-loop mode. Before starting the run loop, the method sends registerForEvents to the application's adaptors so that they can begin receiving run-loop events. Normally, run is invoked in the main function.

See Also: setTimeOut, terminate, terminateAfterTimeInterval


savePage

public void savePage(next.wo.Component aComponent)

Saves the page instance aComponent in the session page cache. The context ID for the current transaction is made the key for obtaining this instance in the cache using restorePageForContextID.


saveSession

public void saveSession(next.wo.WebSession aWebSession)

Saves a WebSession object that represents a session. In normal request handling, this method is called at the end of a cycle of the request-response loop. The default implementation simply invokes SessionStore's saveSession method, but throws an exception if the SessionStore object is missing.

See Also: restoreSession


scriptedClassNameWithPath

public java.lang.String scriptedClassNameWithPath(java.lang.String aPath)

Loads a scripted class with the pathname aPath into the application. The specified script is parsed assuming the default string encoding, and the class and categories found in the script file are dynamically added to the runtime.


scriptedClassNameWithPathEncoding

public java.lang.String scriptedClassNameWithPathEncoding(java.lang.String aPath, int anEncoding)

Loads a scripted class with the pathname aPath using the encoding anEncoding. The class and categories found in the script file are dynamically added to the runtime.


session

public next.wo.WebSession session()

Returns the application's current WebSession object. May not be overridden.

See Also: application, context


sessionStore

public next.wo.SessionStore sessionStore()

Returns the application's current SessionStore object (which, by default, stores state in the server).

See Also: setSessionStore


setBrowserLaunchingEnabled

public void setBrowserLaunchingEnabled(boolean isEnabled)

Controls whether starting up this application also launches a web browser. If isEnabled is true, the application launches the web browser. If false, the application does not launch the browser. Browser launching is enabled by default as long as there is a WOAdaptorURL key in the file NeXT_ROOT/NextLibrary/WOAdaptors/Configuration/WebServerConfig.plist.

To disable web browser launching, you must send this message in your subclass's constructor.

See Also: isBrowserLaunchingEnabled


setCachingEnabled

public void setCachingEnabled(boolean flag)

Enables or disables the caching of component definitions. Component definitions contain templates and other information about pages and subcomponents, and are used to generate instances of those components. When this flag is enabled, the application parses the script (or implementation) file, the HTML, and the declaration (".wod") file of a component once and then stores the resulting component definition. By default, this kind of caching is disabled so that you can edit a scripted component without having to relaunch the application every time to check the results. You should always enable component-definition caching when you deploy an application since performance improves significantly.

Do not confuse this type of caching with page-instance caching (see setPageCacheSize). Caching Strategies in the class description provides further details.

See Also: isCachingEnabled


setMinimumActiveSessionsCount

public void setMinimumActiveSessionsCount(int anInt)

Sets the minimum number of active sessions to anInt. The default is 0.

You use this method to gracefully shut down application instances. If the active sessions count reaches this number and isRefusingNewSessions returns true, the application terminates. You might want to terminate application instances periodically for performance reasons; some applications leak a certain amount of memory per transaction, and shutting down and restarting instances of those applications can free up that memory.

See Also: activeSessionsCount, isRefusingNewSessions, minimumActiveSessionsCount, refuseNewSessions


setPageCacheSize

public void setPageCacheSize(int anInt)

Sets whether caching of page instances will occur and the number of pages the cache will hold. When page-instance caching is enabled, the application stores the Component instance corresponding to the response page in the session. When the page is backtracked to, it restores it from the session and makes it the request page. The state of the page is retained. By default, page-instance caching is enabled, with a cache limit of 30 pages.

You turn page-instance caching off by invoking this method with an argument of zero. In this case, when the user backtracks to a page, the page is not stored in the session and so must be re-created "from scratch." Do not confuse this type of caching with component-definition caching (see setCachingEnabled).

See Caching Strategies in the class description for further details.

See Also: pageCacheSize


setPageRefreshOnBacktrackEnabled

public void setPageRefreshOnBacktrackEnabled(boolean flag)

When flag is true, disables caching of pages by the client by setting the page's expiration-time header to the current date and time. (By default, this attribute is set to false.) Disabling of client caching affects what happens during backtracking. With client caching turned off, the browser resends the URL to the server for the page requested by backtracking. The application must return a new page to the browser (corresponding to a new Component instance). This behavior is desirable when you do not want the user to backtrack to a page that might be obsolete because of changes that have occurred in the session.

When this flag is turned on and a request corresponding to a client backtrack occurs, the retrieved page will only be asked to regenerate its response. The first two phases of a normal request-response loop (value extraction from the request and action invocation) do not occur.

See Caching Strategies in the class description for further details.

See Also: isPageRefreshOnBacktrackEnabled


setPrintsHTMLParserDiagnostics

public void setPrintsHTMLParserDiagnostics(boolean flag)

Sets whether the HTML parser prints warning messages to the standard output device (stdout) if it encounters unbalanced container elements or other syntactically incorrect HTML.

See Also: printsHTMLParserDiagnostics


setResourceManager

public void setResourceManager(next.wo.ResourceManager aResourceManager)

Sets the ResourceManager object to aResourceManager. ResourceManager objects search for and retrieve resources from the application directory and from shared framework directories.

See Also: resourceManager


setSessionStore

public void setSessionStore(next.wo.SessionStore aSessionStore)

Set the session-store object for the application. By default, an object that stores session state in process memory (that is, in the server) is used. The session-store object specifies the state storage strategy for the whole application. This object is responsible for making session objects persistent. WebObjects supports state storage in the server, in the page, and in cookies. You should set the session store object when the application starts up, before the first request is handled.

See Also: sessionStore


setStatisticsStore

public void setStatisticsStore(next.wo.StatisticsStore aStatisticsStore)

Sets the StatisticsStore object to aStatisticsStore. StatisticsStore objects record application statistics while the application runs.


setTimeOut

public void setTimeOut(double aDouble)

Sets the number of seconds the application can experience inactivity (no HTTP requests) before it terminates execution.

This method differs from terminateAfterTimeInterval in that with this method, the application must be idle for aTimeInterval seconds for the application to terminate. terminateAfterTimeInterval terminates the application whether it is active or not.

See Also: timeOut


sleep

public void sleep()

Invoked at the conclusion of a request-handling cycle to give an application the opportunity for deallocating objects created and initialized in its awake method. The default implementation does nothing.


statistics

public next.util.ImmutableHashtable statistics()

Returns a copy of the dictionary containing the application statistics maintained by StatisticsStore. This method is used by the Monitor application to retrieve application statistics. If you need to access the statistics internally, use this message instead:

WebApplication.application().statisticsStore().statistics()

See Also: StatisticsStore class


statisticsStore

public next.wo.StatisticsStore statisticsStore()

Returns the StatisticsStore object, which records statistics while the application runs.

See Also: setStatisticsStore


stringForKeyInTable

public java.lang.String stringForKeyInTable(java.lang.String aString, java.lang.String aString, java.lang.String aString)

Returns a localized string from string table "aTable.strings" using aKey to look it up. If no string value for the key is found in the table, defaultValue (optional) is returned. The method first searches the "aTable.strings" file, if it exists, in each localized (".lproj") subdirectories of the application wrapper; searching proceeds in the order of the language list maintained by the WebSession object. If no string value matching the key is found, the search then continues to the "aTable.strings" file (if it exists) directly under the application wrapper (the directory with the "woa" extension).

See Localization in the class description for further details.


takeValuesFromRequest

public void takeValuesFromRequest(next.wo.Request aRequest, next.wo.Context aContext)

The WebApplication object sends this message to itself to start the first phase of request handling. In this phase, the message is propagated to the session and component objects involved in the request as well as the request page's dynamic elements. Each dynamic element acquires any entered data or changed state (such as a check in a check box) associated with an attribute and assigns the value to the variable bound to the attribute. The default WebApplication implementation of this method forwards the message to the session object.

See Also: appendToResponse, invokeAction


terminate

public void terminate()

Terminates the application process. Termination does not take place until the handling of the current request has completed.

See Also: isTerminating, setTimeOut


terminateAfterTimeInterval

public void terminateAfterTimeInterval(double aTimeInterval)

Sets the application to terminate itself after aTimeInterval seconds has elapsed. After the specified time interval has elapsed, the application immediately stops all current processing. If any sessions are active, users may lose information.

This method differs from setTimeOut in that it does not set idle time; terminateAfterTimeInterval shuts down the application regardless of if it is idle.


timeOut

public double timeOut()

Returns the application's time-out interval: a period (in seconds) of inactivity before the application terminates execution. The default application time-out interval is a very large number.

See Also: setTimeOut


trace

public void trace(boolean flag)

If flag is true, prints all trace messages (messages for scripted messages, compiled messages, and all statements in the application) to the standard error device. If flag is false, stops printing all trace messages.

See Also: traceAssignments, traceObjectiveCMessages, traceScriptedMessages, traceStatements


traceAssignments

public void traceAssignments(boolean flag)

If flag is true, prints a message to the standard error device every time an assignment statement is executed. If flag is false, stops printing trace assignment messages.

See Also: trace, traceObjectiveCMessages, traceScriptedMessages, traceStatements


traceObjectiveCMessages

public void traceObjectiveCMessages(boolean flag)

If flag is true, prints a message to the standard error device every time a message is sent to a compiled class. If flag is false, stops printing these messages.

See Also: trace, traceAssignments, traceScriptedMessages, traceStatements


traceScriptedMessages

public void traceScriptedMessages(boolean flag)

If flag is true, prints a message to the standard error device every time a message is sent to a scripted class. If flag is false, stops printing trace scripted method messages.

See Also: trace, traceAssignments, traceObjectiveCMessages, traceStatements


traceStatements

public void traceStatements(boolean flag)

If flag is true, prints a message to the standard error device every time a statement in the application is executed. If flag is false, stops printing trace statement messages.

See Also: trace, traceAssignments, traceObjectiveCMessages, traceScriptedMessages


urlForResource

public java.lang.String urlForResource(java.lang.String aString, java.lang.String aString)

Returns the URL associated with an application resource having a name of aName and an extension of aType. The method searches all localized application ".lproj" directories before searching directly under the ".woa" wrapper for the resource.

This method is provided for backwards compatibility only. For WebObjects 3.5 and above, you should use the ResourceManager API to retrieve resources.

See Also: stringForKeyInTable