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.
A exception is thrown if initialization
does not succeed.
| The global variable "WOApp"
is initialized in this method. |
Static Methods
public static String adaptor()
Returns the class name of the primary adaptor.
This is the cover method for the user default WOAdaptor.See
Also: setAdaptor
public static NSArray additionalAdaptors()
Returns an array of adaptor description dictionaries.
This is the cover method for the user default WOAdditionalAdaptors.See
Also: setAdditionalAdaptors
public static WOApplication application()
Returns a WOApplication object.You may
call this method, but do not override it.
public static 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
public static boolean autoOpenInBrowser()
Returns whether automatic browser launching
is enabled. By default, automatic browser launching is enabled.
public static 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
public static String componentRequestHandlerKey()
Returns the key which identifies URLs directed
at component-action-based requests. By default, this method returns
the string "wo".
public static 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.
public static String directActionRequestHandlerKey()
Returns the key which identifies URLs directed
at component-based requests. By default, this method returns the
string "wa".
public static 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
public static 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
public static 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
public static 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: setDebuggingEnabled, debugString
public static boolean isDirectConnectEnabled()
Returns whether or not direct connect is enabled.
By default it is enabled. For more information, see setDirectConnectEnabled.See
Also: cgiAdaptorURL
public static 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 comunication with Monitor can
take place. By default, it can communicate with a Monitor application.
'This is a cover method for the user default WOMonitorEnabled. See
Also: setMonitorEnabled, monitorHost, setMonitorHost
public static 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
public static NSArray loadFrameworks()
Returns the array of frameworks to be loaded
during application initialization.See Also: setLoadFrameworks
public static 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);
public static 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
public static 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
public static 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
public static 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
public static 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
public static 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
public static void setAdaptor(String anAdaptorName)
Sets the the class name of the primary adaptor
to anAdaptorName.See
Also: adaptor
public static 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
public static 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
public static 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
public static 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
public static 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
public static void setComponentRequestHandlerKey(String key)
Sets the component request handler key. This
affects all URLs generated during appendToResponse: of component-based
actions.See Also: componentRequestHandlerKey
public static void setDebuggingEnabled(boolean flag)
Sets 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.See
Also: isDebuggingEnabled, debugString
public static void setDirectActionRequestHandlerKey(String key)
Sets the Direct Action request handler key.
This affects all URLs generated during appendToResponse: of direct actions.See
Also: directActionRequestHandlerKey
public static 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
public static 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
public static void setIncludeCommentsInResponses(boolean flag)
Sets whether or not HTML comments are appended
to the response.See Also: includeCommentsInResponses
public static void setListenQueueSize(Number aListenQueueSize)
Sets the size of the listen queue which will
created by the primary adaptor (usually WODefaultAdaptor).See
Also: listenQueueSize
public static void setLoadFrameworks(NSArray frameworkList)
Sets the array of frameworks to be loaded during
application initialization.See Also: loadFrameworks
public static 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
public static 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
public static void setPort(Number port)
Sets the port number on which the primary adaptor
will listen (usually WODefaultAdaptor).See
Also: port
public static void setProjectSearchPath(NSArray searchPath)
Sets the array of file system paths which are
searched for projects for rapid turnaround mode.See
Also: projectSearchPath
public static 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
public static void setResourceRequestHandlerKey(String key)
Sets the resource request handler key. This
affects all URLs generated during appendToResponse of resources.See
Also: resourceRequestHandlerKey
public void setSessionTimeOut(Number aTimeOut)
Accessor to set the default session timeOut.See
Also: sessionTimeout
public static 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
public static 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
public static 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
public static Number workerThreadCount()
Returns the count of worker threads which will
created by the primary adaptor (usually WODefaultAdaptor). A worker
thread count of 0 implies single-threaded mode. This is the cover method
for the user default WOWorkerThreadCount.See
Also: setWorkerThreadCount
Instance Methods
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
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
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.
public boolean adaptorsDispatchRequestsConcurrently()
Returns true if at least one adaptor contains
multiple threads and will attempt to concurrently invoke the request
handlers.
public boolean allowsConcurrentRequestHandling()
Override to return true if concurrent request
handling is allowed.See Also: isConcurrentRequestHandlingEnabled
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 invokeActionForRequest 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: invokeActionForRequest
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
public String baseURL()
Returns the application URL relative to the
server's document root, for example:WebObjects/Examples/HelloWorld.woa.
See
Also: name, path
public WOContext createContextForRequest(WORequest aRequest)
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.
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.
| 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. |
See Also: restoreSessionWithID, saveSessionForContext
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.
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.
public WOResponse dispatchRequest(WORequest aRequest)
The main entry point for any given interaction.
Invoked by the adaptor.
public WODynamicElement dynamicElementWithName(
String aName,
NSDictionary someAssociations,
WOElement anElement
NSArray languages)
Creates and returns a WODynamicElement object
based on the element's name, a dictionary of associations, and
a template of elements. This method is invoked automatically to
provide a WODynamicElement 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 WODynamicElement
or reusable component for one of the built-in WODynamicElements. 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 WODynamicElement
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 WODynamicElement named aName.
If a WODynamicElement 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.
public int garbageCollectionPeriod()
Returns the Java garbage collection period in
seconds. This value can be set with the WOGarbageCollectionPeriodKey
user default or with the setGarbageCollectionPeriod method.
public WOResponse handleException(
Throwable 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.See
Also: handleSessionCreationErrorInContext, handleSessionRestorationErrorInContext
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. See
Also: handleException, handleSessionCreationErrorInContext, handleSessionRestorationErrorInContext
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. See Also: handleException, handlePageRestorationErrorInContext, 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. See Also: handleException, handlePageRestorationErrorInContext, handleSessionCreationErrorInContext
public WORequestHandler handlerForRequest(WORequest aRequest)
Returns the request handler used to handle a
given request.See Also: registerRequestHandler, registeredRequestHandlerKeys, requestHandlerForKey
public WOElement 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
public boolean isConcurrentRequestHandlingEnabled()
Returns true if adaptors dispatch requests concurrently
and allowsConcurrentRequestHandling has been
overridden to allow concurrent request handling.See
Also: allowsConcurrentRequestHandling
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
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.
public boolean isTerminating()
Returns whether the application will terminate
at the end of the current request-response loop. See
Also: setTimeOut, defaultRequestHandler, terminateAfterTimeInterval, timeOut
public void lock()
Locks the application object.
public void lockRequestHandling()
Serializes request handler access if concurrent
request handling isn't enabled.
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.
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.
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
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 ...
public String name()
Returns the name of the application, which is
the name of the executable (without the .exe extension).See
Also: baseURL, path
public String number()
Returns "-1". This is provided for
backwards compatibility only.
public int pageCacheSize()
Returns the size of the internal cache for page
instances. The default size is 30 instances. See
Also: setPageCacheSize
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)
public WOComponent pageWithName(
String aName,
WOContext aContext)
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. See
Also: pageWithName, restorePageForContextID (WOSession), savePage (WOSession)
public String path()
Returns the filesystem 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
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)
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
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
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.See Also: removeRequestHandlerForKey, registeredRequestHandlerKeys, requestHandlerForKey
public NSArray registeredRequestHandlerKeys()
Returns an array of strings containing the keys
of all of the registered request handlers.See
Also: handlerForRequest, requestHandlerForKey
public WORequestHandler removeRequestHandlerForKey(String aRequestHandlerKey)
Removes the specified request handler from the
application.See Also: registerRequestHandler, requestHandlerForKey
public WORequestHandler requestHandlerForKey(String key)
Returns the request handler used to handle requests
containing the specified key.See Also: handlerForRequest, registerRequestHandler, registeredRequestHandlerKeys
public boolean requiresWOF35RequestHandling()
For backward compatibility, if your project
depends upon features or side effects of the old request handling,
you will want to override this method and return true. By default,
it returns false.
public boolean requiresWOF35TemplateParser()
For backward compatibility, if your project
depends upon features or side effects removed from the new, 4.0
template parser, you will want to override this method and return true.
By default, it returns false.
public WOResourceManager resourceManager()
Returns the WOResourceManager object that the
application uses to manage resources. See
Also: setResourceManager
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. See
Also: createSessionForRequest, saveSessionForContext
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, defaultRequestHandler, terminateAfterTimeInterval
public NSRunLoop runLoop()
Returns the application's run loop. Use this
method when you need a run loop for such things as registering timers.
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
public String scriptedClassNameWithPath(String aPath)
Loads a Webscript-based 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.
public String scriptedClassNameWithPathEncoding(
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. The script must use the @interface/@implementation
syntax.
public WOSessionStore sessionStore()
Returns the application's current WOSessionStore
object (which, by default, stores state in the server). See
Also: setSessionStore
public void setDefaultRequestHandler(WORequestHandler aHandler)
Sets the default request handler.
See
Also: defaultRequestHandler
public void setGarbageCollectionPeriod(int seconds)
Sets the Java garbage collection period to seconds.
This period can also be set using the WOGarbageCollectionPeriod
user default.
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
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
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
public void setPermanentPageCacheSize(int aSize)
Sets the permanentPageCacheSize to aSizeSee
Also: permanentPageCacheSize
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: setDebuggingEnabled, debugString
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
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
public void setStatisticsStore(WOStatisticsStore aStatisticsStore)
Sets the WOStatisticsStore object to aStatisticsStore.
WOStatisticsStore objects record application statistics while the
application runs. See Also: statisticsStore
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
public com.apple.yellow.eocontrol.EOSharedEditingContext sharedEditingContext()
This is a convenience method that returns
the default shared editing context.
See
Also: EOSharedEditingContext class description in
the EOControl Framework
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.
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()
public WOStatisticsStore statisticsStore()
Returns the WOStatisticsStore object, which
records statistics while the application runs. See
Also: setStatisticsStore
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, invokeActionForRequest
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
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.
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
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
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
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 from
Webscript. If flag is false, stops printing these messages. See
Also: trace, traceAssignments, traceScriptedMessages, traceStatements
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 from
Webscript. If flag is false, stops printing trace scripted method
messages. See Also: trace, traceAssignments, traceObjectiveCMessages, 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
from Webscript. If flag is false, stops printing trace statement
messages. See Also: trace, traceAssignments, traceObjectiveCMessages, traceScriptedMessages
public void unlock()
Unlocks the application object.
public void unlockRequestHandling()
Disables serialized request handler access if
concurrent request handling isn't enabled.
