WOApplication

Inherits from:
Object

Implements:
NSKeyValueCoding
NSKeyValueCoding.ErrorHandling
NSKeyValueCodingAdditions

Package:
com.webobjects.appserver

Class Description

The primary role of the WOApplication class is to coordinate the handling of HTTP requests. Each application must have exactly one WOApplication 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 WOSession 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, WOApplication 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, coordinates the different levels of multi-threaded execution, and furnishes a variety of data.

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 WOApplication class or you can obtain the application object from a custom subclass of WOApplication. Custom WOApplication subclasses are common in WebObjects applications since there is often a need to override the awake, sleep, and request-handling methods. Compiled WOApplication 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 WOApplication subclass automatically created at run time; the application object is instantiated from this subclass.

Constants

WOApplication declares class variables:

Class Variable	Description
ApplicationDidDispatchRequestNotification	This class variable contains a String that names the notification posted at the very beginning of WOApplication's dispatchRequest(WORequest) method.
ApplicationDidFinishLaunchingNotification	This class variable contains a String that names the notification posted by WOApplication's run() method after the application is launched. This notification is posted when the run() method logs the "Waiting for requests..." message to the console.
ApplicationWillDispatchRequestNotification	This class variable contains a String that names the notification posted at the end of WOApplication's dispatchRequest(WORequest) method.
ApplicationWillFinishLaunchingNotification	This class variable contains a String that names the notification posted at the very beginning of WOApplication's run() method.

Interfaces Implemented

NSKeyValueCoding
takeValueForKey
valueForKey

NSKeyValueCoding.ErrorHandling
handleQueryWithUnboundKey
handleTakeValueForUnboundKey
unableToSetNullForKey

NSKeyValueCodingAdditions
takeValuesFromRequest
valueForKeyPath

Method Types

Creating
WOApplication
Obtaining attributes
adaptorsDispatchRequestsConcurrently
allowsConcurrentRequestHandling
isConcurrentRequestHandlingEnabled
baseURL
name
number
path
Locking
lock
unlock
Managing adaptors
adaptorWithName
adaptors
Managing sessions
setSessionStore
sessionStore
saveSessionForContext
restoreSessionWithID
createSessionForRequest
Managing pages
setPageCacheSize
pageCacheSize
permanentPageCacheSize
setPermanentPageCacheSize
setPageRefreshOnBacktrackEnabled
isPageRefreshOnBacktrackEnabled
pageWithName
pageWithName
Creating elements
dynamicElementWithName
Running
run
setTimeOut
timeOut
defaultRequestHandler
terminate
terminateAfterTimeInterval
Handling requests
appendToResponse
awake
createContextForRequest
createSessionForRequest
defaultRequestHandler
defaultRequestHandlerClassName
dispatchRequest
handlerForRequest
invokeAction
registeredRequestHandlerKeys
registerRequestHandler
removeRequestHandlerForKey
requestHandlerForKey
setDefaultRequestHandler
sleep
takeValuesFromRequest
Handling errors
handleSessionCreationErrorInContext
handlePageRestorationErrorInContext
handleSessionRestorationErrorInContext
handleException
Script debugging
logString
debugString
printsHTMLParserDiagnostics
setPrintsHTMLParserDiagnostics
logTakeValueForDeclarationNamed
logSetValueForDeclarationNamed
Statistics report
setStatisticsStore
statisticsStore
statistics
Monitor support
monitorEnabled
monitoringEnabled
activeSessionsCount
refuseNewSessions
isRefusingNewSessions
setMinimumActiveSessionsCount
minimumActiveSessionsCount
terminateAfterTimeInterval
Resource manager support
setResourceManager
resourceManager
User defaults
loadFrameworks
setLoadFrameworks
isDebuggingEnabled
autoOpenInBrowser
setAutoOpenInBrowser
isDirectConnectEnabled
setDirectConnectEnabled
cgiAdaptorURL
setCGIAdaptorURL
isCachingEnabled
setCachingEnabled
applicationBaseURL
setApplicationBaseURL
frameworksBaseURL
setFrameworksBaseURL
recordingPath
setRecordingPath
projectSearchPath
setProjectSearchPath
isMonitorEnabled
setMonitorEnabled
monitorHost
setMonitorHost
SMTPHost
setSMTPHost
adaptor
setAdaptor
port
setPort
listenQueueSize
setListenQueueSize
workerThreadCount
setWorkerThreadCount
additionalAdaptors
setAdditionalAdaptors
includeCommentsInResponses
setIncludeCommentsInResponses
componentRequestHandlerKey
setComponentRequestHandlerKey
directActionRequestHandlerKey
setDirectActionRequestHandlerKey
resourceRequestHandlerKey
setResourceRequestHandlerKey
sessionTimeout
setSessionTimeOut
Convenience Methods
sharedEditingContext

Constructors

WOApplication

public WOApplication()

Creates and initializes application attributes and initializes the adaptor or adaptors specified on the command line. If no adaptor is specified, WODefaultAdaptor is made the default adaptor. Some of the more interesting attribute initializations are:

Session store is in the server.
Page cache size is 30 pages.
Client caching of pages is enabled ( isPageRefreshOnBacktrackEnabled returns false).

A exception is thrown if initialization does not succeed.

Note: The global variable "WOApp" is initialized in this method.

Static Methods

application

public static WOApplication application()

Returns a WOApplication object.

You may call this method, but do not override it.

licensedRequestLimit

public static final int licensedRequestLimit()

This static final method returns an int that represents the request limit license value.

licensedRequestWindow

public static final long licensedRequestWindow()

This static final method returns a long containing the license value of the request window, in milliseconds (this is the amount of time WebObjects pauses per request once the license limit has been hit).

licensingAllowsMultipleInstances

public static final boolean licensingAllowsMultipleInstances()

This static final method returns a boolean indicating whether the license allows multiple instances of the application to run simultaneously.

licensingAllowsMultipleThreads

public static final boolean licensingAllowsMultipleThreads()

This static final method returns a boolean that indicates whether the application is allowed to run in multithreaded mode.

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

WOApplication's implementation of this static method returns true, indicating that key/value coding is allowed to access fields in this object if an appropriate method isn't present.

main

public static void main(String[] argv[])

The WebObjects application's main method.

public static void main(String[] argv[], Class applicationClass)

An alternate main method for your WebObjects applications that allows you to specify a subclass of WOApplication to be instantiated and run instead of WOApplication.

Instance Methods

activeSessionsCount

public synchronized 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.

adaptorWithName

public WOAdaptor adaptorWithName( String aName, NSDictionary someArguments)

Invoked during the constructor to create an adaptor. If you subclass WOAdaptor, you specify the WOAdaptor subclass you want the application to use with the -a option on the application's command line. When WOApplication encounters the -a option, it invokes this method. This method looks for a subclass of WOAdaptor 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 WOAdaptor class for more information.

See Also: adaptors

adaptor

public String adaptor()

Returns the class name of the primary adaptor. This is the cover method for the user default WOAdaptor.

See Also: setAdaptor

adaptors

public NSArray adaptors()

Returns the current list of application adaptors. A WOApplication can have multiple adaptors. (To associate the WOApplication 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 WODefaultAdaptor), but can also receive remote request messages using more advanced RPC mechanisms such as DO, CORBA, and DCOM.

adaptorsDispatchRequestsConcurrently

public final boolean adaptorsDispatchRequestsConcurrently()

Returns true if at least one adaptor contains multiple threads and will attempt to concurrently invoke the request handlers.

additionalAdaptors

public NSArray additionalAdaptors()

Returns an array of adaptor description dictionaries. This is the cover method for the user default WOAdditionalAdaptors.

See Also: setAdditionalAdaptors

allowsConcurrentRequestHandling

public boolean allowsConcurrentRequestHandling()

Override to return true if concurrent request handling is allowed.

appendToResponse

public void appendToResponse( WOResponse aResponse, WOContext aContext)

The WOApplication 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. WOApplication's default implementation of this method forwards the message to the session object.

See Also: invokeAction

applicationBaseURL

public String applicationBaseURL()

Returns a path to where the current application may be found under the document root (either the project or the .woa wrapper). This is the cover method for the user default WOApplicationBaseURL.

See Also: setApplicationBaseURL

autoOpenInBrowser

public boolean autoOpenInBrowser()

Returns whether automatic browser launching is enabled. By default, automatic browser launching is enabled.

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 String baseURL()

Returns the application URL relative to the server's document root, for example:


WebObjects/Examples/HelloWorld.woa.

See Also: name, path

cgiAdaptorURL

public String cgiAdaptorURL()

Returns the URL for the web server including the path to the WebObjects CGI adaptor (for example, http://localhost/cgi-bin/WebObjects). This URL is used by the direct connect feature only. This is the cover for the user default WOCGIAdaptorURL.

See Also: setCGIAdaptorURL

componentRequestHandlerKey

public String componentRequestHandlerKey()

Returns the key which identifies URLs directed at component-action-based requests. By default, this method returns the string "wo".

createContextForRequest

public WOContext createContextForRequest(WORequestaRequest)

Creates a new context object for a given request. Override this method if you need to provide your own subclass of WOContext. If you override it, your implementation need not call super.

createRequest

public WORequest createRequest( String aMethod, String aURL, String anHTTPVersion, NSDictionary someHeaders, NSData aContent, NSDictionary someInfo)

Convenience method that instantiates and returns a new WORequest object.

createResponseInContext

public WOResponse createResponseInContext(WOContext aContext)

Convenience method that instantiates and returns a new, empty WOResponse object.

createSessionForRequest

public WOSession createSessionForRequest(WORequest aRequest)

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

First it looks for a compiled class of name "Session" that is a subclass of WOSession.
If such a class does not exist, it looks for a ".wos" script with the name of "Session" in the application wrapper (".woa" directory).
If the Session.wos script exists, the method parses the script and dynamically adds a scripted-class subclass of WOSession to the runtime.

The method then returns an allocated and initialized (using the default WOSession 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 WOSession subclasses should be "Session"; if not, you will have to override this method to use the proper class to create the session object.

defaultRequestHandler

public WORequestHandler defaultRequestHandler()

Returns the request handler to be used when no request handler key was found in the URL or WORequest. This method returns the WOComponent request handler by default. When an application is contacted for the first time it is usually via a URL like the following:



http://somehost/cgi-bin/WebObjects/AppName.woa

The way that URLs of that type are handled is determined by the default request handler.

defaultRequestHandlerClassName

public String defaultRequestHandlerClassName()

The default implementation of this method returns "WOComponentRequestHandler", which is the default request handler. Override this method to return "WODirectActionRequestHandler" to make the direct action request handler the default.

debugString

public void debugString(String aFormatString)

Prints a message to the standard error device (stderr), if WODebuggingEnabled is true. The message can include formatted variable data using String's concatenation feature.

You control whether this method displays output with the WODebuggingEnabled user default option. If WODebuggingEnabled is true, then the debugString messages display their output. If WODebuggingEnabled is false, the debugString messages don't display their output.

directActionRequestHandlerKey

public String directActionRequestHandlerKey()

Returns the key which identifies URLs directed at component-based requests. By default, this method returns the string "wa".

dispatchRequest

public WOResponse dispatchRequest(WORequest aRequest)

The main entry point for any given interaction. Invoked by the adaptor.

dynamicElementWithName

public WOElement dynamicElementWithName( String aName, NSDictionary someAssociations, WOElement anElement NSArray languages)

Creates and returns a WOElement object based on the element's name, a dictionary of associations, and a template of elements. This method is invoked automatically to provide a WOElement 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 WOElement or reusable component for one of the built-in WOElements.

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 WOElement 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 WOAssociation objects.

WOApplication's implementation of dynamicElementWithName first searches for a WOElement named aName. If a WOElement 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.

finalize

protected void finalize() throws Throwable

WOApplication's finalizer. This protected method frees up resources that are used internally by the WOApplication object.

frameworksBaseURL

public String frameworksBaseURL()

Returns a path to where all frameworks may be found under the document root. This value is used to determine URLs that should be generated to reference Web Server Resources in those frameworks. This is the cover method for the user default WOFrameworksBaseURL.

See Also: setFrameworksBaseURL

handleException

public WOResponse handleException( Exception anException, WOContext aContext)

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.

handlePageRestorationErrorInContext

public WOResponse handlePageRestorationErrorInContext(WOContext aContext)

Invoked when a page (WOComponent) 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.

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling.

handleSessionCreationErrorInContext

public WOResponse handleSessionCreationErrorInContext(WOContext aContext)

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

handleSessionRestorationErrorInContext

public WOResponse handleSessionRestorationErrorInContext(WOContext aContext)

Invoked when a session (WOSession) 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.

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value, String key)

Conformance to NSKeyValueCoding.ErrorHandling.

handlerForRequest

public WORequestHandler handlerForRequest(WORequest aRequest)

Returns the request handler used to handle a given request.

includeCommentsInResponses

public boolean includeCommentsInResponses()

Returns whether or not HTML comments are appended to the response. This is the cover method for the user default WOIncludeCommentsInResponses.

See Also: setIncludeCommentsInResponses

invokeAction

public WOActionResults invokeAction( WORequest aRequest, WOContext aContext)

The WOApplication 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. The default WOApplication implementation of this method forwards the message to the session object.

See Also: appendToResponse

isCachingEnabled

public boolean isCachingEnabled()

Returns whether or not component caching is enabled. If this is enabled, changes to a component will be reparsed after being saved (assuming the project is under the NSProjectSearchPath). Note that this has no effect on page caching. This is the cover method for the user default WOCachingEnabled.

See Also: setCachingEnabled, pageCacheSize

isConcurrentRequestHandlingEnabled

public final boolean isConcurrentRequestHandlingEnabled()

Returns true if adaptors dispatch requests concurrently and allowsConcurrentRequestHandling has been overridden to allow concurrent request handling.

See Also: allowsConcurrentRequestHandling

isDebuggingEnabled

public boolean isDebuggingEnabled()

Returns whether or not debugging is enabled. If true, debugString prints out. Most startup-time status message are supressed if this method returns false. By default, debugging is enabled. This is the cover method for the user default WODebuggingEnabled.

See Also: debugString

isDirectConnectEnabled

public boolean isDirectConnectEnabled()

Returns whether or not direct connect is enabled. By default it is enabled. For more information, see setDirectConnectEnabled.

See Also: cgiAdaptorURL

isMonitorEnabled

public boolean isMonitorEnabled()

Returns whether or not the application can communicate with a Monitor application. It returns true if the application can contact Monitor upon startup and subsequently let Monitor gather statistics. It returns false if no communication with Monitor can take place. By default, it can communicate with a Monitor application. 'This is a cover method for the user default WOMonitorEnabled.

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.

isTerminating

public boolean isTerminating()

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

lifebeatDestinationPort

public int lifebeatDestinationPort()

Returns an int indicating the port to which application lifebeat signals are to be sent. This port value is controlled by the WOLifebeatDestinationPort key and by the setLifebeatDestinationPort(int) method.

lifebeatEnabled

public boolean lifebeatEnabled()

Description forthcoming.

lifebeatInterval

public int lifebeatInterval()

Description forthcoming.

listenQueueSize

public Number listenQueueSize()

Returns the size of the listen queue which will created by the primary adaptor (usually WODefaultAdaptor). This is the cover method for the user default WOListenQueueSize.

See Also: setListenQueueSize

loadFrameworks

public NSArray loadFrameworks()

Returns the array of frameworks to be loaded during application initialization.

See Also: setLoadFrameworks

lock

public void lock()

Locks the application object.

logSetValueForDeclarationNamed

public void logSetValueForDeclarationNamed( String aDeclarationName, String aDeclarationType, String aBindingName, String anAssociationDescription, Object aValue)

Formats and logs a message anytime a value is set through a WOAssociation, when WODebug is set to true for the declaration in which the association appears. (Setting a value means the child component/element is setting a value in the parent). See logTakeValueForDeclarationNamed for a description of each of the arguments to this method.

logString

public void logString(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;
WOApplication.logString("Amount = " + i + ", Rate = " + f ", Total = " + i*f);

logTakeValueForDeclarationNamed

public void logTakeValueForDeclarationNamed( String aDeclarationName, String aDeclarationType, String aBindingName, String anAssociationDescription, Object aValue)

Formats and logs a message anytime a value is "taken" through a WOAssociation , when WODebug is set to true for the declaration in which the association appears. (Taking a value means the child component/element is taking a value from the parent). Override this method to alter the format of the log message. The arguments of this method are defined in the following example of a WebObjects declaration.


aDeclarationName : aDeclarationType {
    aBindingName = anAssociationDescription;
}

Also, aValue is the value which is being pushed to or pulled from the child to the parent.

maxSocketIdleTime

public Number maxSocketIdleTime()

Returns a Number indicating the maximum amount of time a socket is allowed to idle. This value is controlled by the WOMaxSocketIdleTime key and by the setMaxSocketIdleTime(Number) method.

See Also: setMaxSocketIdleTime

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.

monitorEnabled

public boolean monitorEnabled()

Description forthcoming.

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 -WOMonitorEnabled NO 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 -WOMonitorEnabled YES -WOMonitorHost monitorHost ...

monitorHost

public String monitorHost()

Returns the host on which Monitor is assumed to be running. This value is used during initialization if isMonitorEnabled returns true. This is a cover for the user default WOMonitorHost.

See Also: setMonitorHost, isMonitorEnabled

name

public String name()

Returns the name of the application, which is the name of the executable (without the .exe extension).

See Also: baseURL, path

number

public String number()

Returns "-1". This is provided for backwards compatibility only.

outputPath

public String outputPath()

Description forthcoming.

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 WOComponent pageWithName( String aName, WORequest aRequest)

Returns a new page instance (a WOComponent 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.

As part of its implementation, this method creates a context with aRequest and calls pageWithName.

See Also: restorePageForContextID (WOSession), savePage (WOSession)

pageWithName

public WOComponent pageWithName( String aName, WOContext aContext)

See Also: pageWithName, restorePageForContextID (WOSession), savePage (WOSession)

path

public String path()

Returns the file system path of the application, which is an absolute path and includes the ".woa" extension; for example "C:/NETSCAPE/ns-home/docs/WebObjects/Examples/HelloWorld.woa" is a typical application path.

See Also: baseURL, name

permanentPageCacheSize

public int permanentPageCacheSize()

Returns the permanent page cache size. The default is 30. The permanent page cache holds pages which should not fall out of the regular page cache. For example, a control page in a frameset should exist for the duration of a session.

See Also: savePageInPermanentCache ( WOApplication)

port

public Number port()

Returns the port number on which the primary adaptor will listen (usually WODefaultAdaptor). This is the cover method for the user default WOPort.

See Also: setPort

printsHTMLParserDiagnostics

public boolean printsHTMLParserDiagnostics()

Returns whether the HTML parser prints diagnostic information to stdout when it encounters unbalanced HTML containers or other syntactically incorrect HTML. This method returns false by default.

See Also: isDebuggingEnabled debugString

projectSearchPath

public NSArray projectSearchPath()

Returns an array of file system paths which are searched for projects for rapid turnaround mode. This is the cover method for the user default NSProjectSearchPath.

See Also: setProjectSearchPath

recordingPath

public String recordingPath()

Returns a file system path which is where the recording information should be saved. By default, this method returns null.

If this method returns a path, all requests and responses are recorded in the HTTP format in numbered files (0000-request, 0000-response, 0001-request, 0001-response, and so on), and saved under the recording path specified. This directory is then used by the Playback tool to test the application. You will most likely set this as a command line argument (-WORecordingPath pathname), exercise your application to record a scenario you would like to test, and then stop the application. Afterward you can restart the application without the WORecordingPath argument, and point Playback to the recording directory just created to replay your sequence of requests and compare the responses received with the ones recorded.

See Also: setRecordingPath

refuseNewSessions

public synchronized 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.

registerRequestHandler

public void registerRequestHandler( WORequestHandler aHandler, String aKey)

Registers a new request handler. aKey must specify a key which can be found in the URLs following the instance number or application name.

registeredRequestHandlerKeys

public NSArray registeredRequestHandlerKeys()

Returns an array of strings containing the keys of all of the registered request handlers.

See Also: handlerForRequest, requestHandlerForKey

removeRequestHandlerForKey

public WORequestHandler removeRequestHandlerForKey(String aRequestHandlerKey)

Removes the specified request handler from the application.

requestHandlerForKey

public WORequestHandler requestHandlerForKey(String key)

Returns the request handler used to handle requests containing the specified key.

requestHandlingLock

public Object requestHandlingLock()

Returns an Object suitable for a synchronization lock, or null if the application isn't multithreaded.

resourceManager

public WOResourceManager resourceManager()

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

See Also: setResourceManager

resourceRequestHandlerKey

public String resourceRequestHandlerKey()

Returns the key which identifies URLs directed through the resource request handler. Resource requests are only used during development of an application when the application is being run without an HTTP server.

See Also: setResourceRequestHandlerKey

restoreSessionWithID

public WOSession restoreSessionWithID( String aSessionID, WOContext aContext)

Restores the WOSession object representing a session. In normal request handling, this method is invoked at the start of a cycle of the request-response loop. The default implementation simply invokes WOSessionStore's checkOutSessionWithID method, but raises an exception if the WOSessionStore object is missing.

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.

saveSessionForContext

public void saveSessionForContext(WOContext aContext)

Called at the end of the request handling loop, when the current session object needs to be saved. The default implementation simply invokes WOSessionStore's checkInSessionForContext method, but throws an exception if the WOSessionStore object is missing.

See Also: restoreSessionWithID

sessionStore

public WOSessionStore sessionStore()

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

See Also: setSessionStore

sessionStoreClassName

public String sessionStoreClassName()

Returns, as a String, the value of the WOSessionStoreClassName key. The default value for this key is "WOServerSessionStore".

sessionTimeout

public Number sessionTimeOut()

Returns the number (of seconds) which will be used as the default timeout for each newly created session. You may either override this method, change the user default WOSessionTimeOut, or set the session timeout in your session's init method.

See Also: setSessionTimeOut

setAdaptor

public void setAdaptor(String anAdaptorName)

Sets the the class name of the primary adaptor to anAdaptorName.

See Also: adaptor

setAdditionalAdaptors

public void setAdditionalAdaptors(NSArray anAdaptorPlist)

Sets the array of adaptor description dictionaries to anAdaptorPlist. Each adaptor description dictionary must have "WOAdaptor" defined, which is the name of the adaptor class. Other attributes such as WOPort may also be specified, but are adaptor specific. For example WOWorkerThreadCount is specific to the WODefaultAdaptor class and may not apply for all adaptors.

See Also: additionalAdaptors

setAllowsConcurrentRequestHandling

public void setAllowsConcurrentRequestHandling(boolean aValue)

Explicitly specifies whether concurrent request handling is allowed. If your code does not invoke this method, the value of the WOAllowsConcurrentRequestHandling (interpreted as a boolean) determines whether concurrent request handling is allowed.

setApplicationBaseURL

public void setApplicationBaseURL(String aBaseURL)

Sets to aBaseURL the path to which the current application may be found under the document root (either the project or the .woa wrapper).

See Also: applicationBaseURL

setAutoOpenInBrowser

public void setAutoOpenInBrowser(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: autoOpenInBrowser

setCachingEnabled

public void setCachingEnabled(boolean flag)

Sets whether or not component caching is enabled. If this is enabled, changes to a component will be reparsed after being saved (assuming the project is under the NSProjectSearchPath). Note that this has no effect on page caching.

See Also: isCachingEnabled, pageCacheSize

setCGIAdaptorURL

public void setCGIAdaptorURL(String aURL)

Sets the URL for the web server to aURL. The URL must include the path to the WebObjects CGI adaptor (for example, http://localhost/cgi-bin/WebObjects). This URL is used by the direct connect feature only..

See Also: cgiAdaptorURL

setComponentRequestHandlerKey

public void setComponentRequestHandlerKey(String key)

Sets the component request handler key. This affects all URLs generated during appendToResponse: of component-based actions.

See Also: componentRequestHandlerKey

setDefaultRequestHandler

public void setDefaultRequestHandler(WORequestHandler aHandler)

Sets the default request handler.

See Also: defaultRequestHandler

setDirectActionRequestHandlerKey

public void setDirectActionRequestHandlerKey(String key)

Sets the Direct Action request handler key. This affects all URLs generated during appendToResponse: of direct actions.

See Also: directActionRequestHandlerKey

setDirectConnectEnabled

public void setDirectConnectEnabled(boolean flag)

Sets whether or not direct connect is enabled. By default it is enabled.

Direct connect actually transforms your application in a simple web server of its own. In particular, it is then able to find and return its images and resources as if it were a web server. It is very useful in development mode: You don't need a web server. Just point your URL to the port where your application is listening, and the application will handle all urls.

If this flag is true, the following happens:

When using autoOpenInBrowser, a direct connect URL will be used.
When using WOMailDelivery to mail pages with dynamic links in them, these links will be generated with a complete direct connect URL format. People receiving these mails will be able to access the application with direct connect.
All files on the system are accessible through the resource request handler. On the other hand, if this flag is false, the resource request handler can be used to retrieve data objects from memory only, and no more reading in the file system is permitted (secure mode for deployment).

See Also: isDirectConnectEnabled, cgiAdaptorURL

setFrameworksBaseURL

public void setFrameworksBaseURL(String aString)

Sets to aString the path to where all frameworks may be found under the document root. This value is used to determine URLs that should be generated to reference Web Server Resources in those frameworks.

See Also: frameworksBaseURL

setIncludeCommentsInResponses

public void setIncludeCommentsInResponses(boolean flag)

Sets whether or not HTML comments are appended to the response.

See Also: includeCommentsInResponses

setListenQueueSize

public void setListenQueueSize(Number aListenQueueSize)

Sets the size of the listen queue which will created by the primary adaptor (usually WODefaultAdaptor).

See Also: listenQueueSize

setLoadFrameworks

public void setLoadFrameworks(NSArray frameworkList)

Sets the array of frameworks to be loaded during application initialization.

See Also: loadFrameworks

setMaxSocketIdleTime

public void setMaxSocketIdleTime(Number maxSocketIdleTime)

Specifies the maximum amount of time a socket should be allowed to idle. The value specified to this method takes precedence over the WOMaxSocketIdleTime key.

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

setMonitorEnabled

public void setMonitorEnabled(boolean flag)

Sets whether or not the application will communicate with a Monitor application. If flag is true, the application can contact Monitor upon startup and subsequently let Monitor gather statistics. If flag is false, no comunication with Monitor can take place. By default, it can communicate with a Monitor application.

See Also: isMonitorEnabled

setMonitorHost

public void setMonitorHost(String hostName)

Sets the host on which Monitor is assumed to be running. This value is used during initialization if isMonitorEnabled returns true.

See Also: monitorHost, isMonitorEnabled

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 WOComponent 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."

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 WOComponent 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

setPermanentPageCacheSize

public void setPermanentPageCacheSize(int aSize)

Sets the permanentPageCacheSize to aSize

See Also: permanentPageCacheSize

setPort

public void setPort(Number port)

Sets the port number on which the primary adaptor will listen (usually WODefaultAdaptor).

See Also: port

setPrintsHTMLParserDiagnostics

public void setPrintsHTMLParserDiagnostics(boolean flag)

Sets whether the HTML parser prints diagnostic information to stdout when it encounters unbalanced HTML containers or other syntactically incorrect HTML. This diagnostic information is not printed by default.

See Also: debugString

setProjectSearchPath

public void setProjectSearchPath(NSArray searchPath)

Sets the array of file system paths which are searched for projects for rapid turnaround mode.

See Also: projectSearchPath

setRecordingPath

public void setRecordingPath(String path)

Sets the file system path where the recording information should be saved. Use null as the path if you don't want to save recording information. By default, recording information is not saved.

If you save recording information, all requests and responses are recorded in the HTTP format in numbered files (0000-request, 0000-response, 0001-request, 0001-response, and so on), and saved under the recording path specified. This directory is then used by the Playback tool to test the application. You will most likely set this as a command line argument (-WORecordingPath pathname), exercise your application to record a scenario you would like to test, and then stop the application. Afterward you can restart the application without the WORecordingPath argument, and point Playback to the recording directory just created to replay your sequence of requests and compare the responses received with the ones recorded.

See Also: recordingPath

setResourceManager

public void setResourceManager(WOResourceManager aResourceManager)

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

See Also: resourceManager

setResourceRequestHandlerKey

public void setResourceRequestHandlerKey(String key)

Sets the resource request handler key. This affects all URLs generated during appendToResponse of resources.

See Also: resourceRequestHandlerKey

setSessionStore

public void setSessionStore(WOSessionStore 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. You should set the session store object when the application starts up, before the first request is handled.

See Also: sessionStore

setSessionStoreClassName

public void setSessionStoreClassName(String aString)

Sets the name of the session store class to the specified name. The value specified to this method takes precedence over the WOSessionStoreClassName key.

setSessionTimeOut

public void setSessionTimeOut(Number aTimeOut)

Accessor to set the default session timeOut.

See Also: sessionTimeout

setSMTPHost

public void setSMTPHost(String hostName)

Sets the name of the host that will be used to send e-mail messages created by WOMailDelivery.

See Also: SMTPHost

setSocketCacheSize

public void setSocketCacheSize(Number socketCacheSize)

Specifies the maximum number of sockets to retain in the socket cache. If you don't explicitly specify the number of sockets with this method, the socket cache size will be determined by the value of the WOSocketCacheSize key, which has a default value of 100.

setSocketMonitorSleepTime

public void setSocketMonitorSleepTime(Number socketMonitorSleepTime)

Sets the length of time (in milliseconds) that the socket monitor will sleep in order to allow the worker threads to operate. If you don't invoke this method, the value of the WOSocketMonitorSleepTime key will be used (the default value for this key is 50 msec).

setStatisticsStore

public void setStatisticsStore(WOStatisticsStore aStatisticsStore)

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

See Also: statisticsStore

setWorkerThreadCount

public void setWorkerThreadCount(Number aWorkerThreadCount)

SEts the count of worker threads which will created by the primary adaptor (usually WODefaultAdaptor). A worker thread count of 0 implies single-threaded mode.

See Also: workerThreadCount

setTimeOut

public void setTimeOut(double aTimeInterval)

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

sharedEditingContext

public com.webobjects.eocontrol.EOSharedEditingContext sharedEditingContext()

This is a convenience method that returns the default shared editing context.

See Also: EOSharedEditingContext class description in the EOControl Framework

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.

SMTPHost

public String SMTPHost()

Returns the name of the host that will be used to send e-mail messages created by WOMailDelivery. This is the cover method for the user default WOSMTPHost.

See Also: setSMTPHost

socketCacheSize

public Number socketCacheSize()

Returns a Number indicating the maximum number of sockets that can be held in the socket cache. The default cache size is 100.

See Also: setSocketCacheSize

socketMonitorSleepTime

public Number socketMonitorSleepTime()

Returns a Number indicating the length of time (in milliseconds) that the socket monitor will sleep in order to allow the worker threads to operate. The default is 50 milliseconds.

See Also: setSocketMonitorSleepTime

statistics

public NSDictionary statistics()

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


WOApplication.application().statisticsStore().statistics()

statisticsStore

public WOStatisticsStore statisticsStore()

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

See Also: setStatisticsStore

takeValueForKey

public void takeValueForKey(Object value, String key)

Conformance to NSKeyValueCoding.

takeValueForKeyPath

public void takeValueForKeyPath(Object value, String keyPath)

Conformance to NSKeyValueCodingAdditions.

takeValuesFromRequest

public void takeValuesFromRequest( WORequest aRequest, WOContext aContext)

The component action request handler sends this message to the WOApplication 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 WOApplication 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 whether 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

See Also: setWorkerThreadCount