com.portal.bas

Class PClientServices

java.lang.Object

com.portal.bas.PClientServices

Direct Known Subclasses:

PAppletServices, PApplicationServices, PBuilderServices, PClientApplicationServices, PPooledConnectionClientServices

public abstract class PClientServices
extends Object

PClientServices is an interface that defines methods that must be implemented in all client classes. This interface includes methods for getting resources, connecting to Portal, getting permissions, and so forth. Services that are specific to the application type (applet, application, or build-time component) are provided by specific subclasses, which are retrieved through a factory method in PClientContext.

BAS needs to be initalized using one of two methods: init() or doLogin(). doLogin internally creates a connection to Portal based on the login information supplied. init() allows initializing BAS using an existing PortalContext.

Author:

Larry Lynch-Freshner

See Also:

PClientContext

Field Summary

Fields

Modifier and Type	Field and Description
protected PBAServer	mBAServer
protected PInfranetConnection	mConnection
protected oracle.help.CSHManager	mCSHManager
protected Properties	mDefaults
protected oracle.help.Help	mHelp
protected oracle.help.library.helpset.HelpSet	mHelpSet
protected ThreadPool	mPool
protected ResourceBundle	mResources
protected static String	RESKEY

Constructor Summary

Constructors

Constructor and Description
PClientServices()

Method Summary

Modifier and Type	Method and Description
void	addResourceBundle(String res) Adds resources to the internal stack.
int	confirmationMsg(String msg) Display a confirmation dialog containing the specified message and 2 choices for the user (YES or NO).
int	confirmationMsg(String msg, int def) Display a confirmation dialog containing the specified message, default title and 2 choices for the user (YES or NO).
int	confirmationMsg(String msg, String title) Display a confirmation dialog containing the specified message, title and 2 choices for the user (YES or NO).
int	confirmationMsg(String msg, String title, int def) Display a confirmation dialog containing the specified message, title and 2 choices for the user (YES or NO).
boolean	connect(String name, String password, String connectInfo) Uses login information to establish a connection with Portal and initialize BAS subsystem.
Object	createClass(String className) Used to dynamically create instances of Customer Center beans and drilldowns and provide the ability for customers to override them.
PInfranetException	createClientException(EBufException ebuf)
PControllerBean	createController(String controllerClass) Registers an Portal component with the server.
Object	createDialogClass(String className, boolean isModal, String title)
static PModelHandle	createModelHandle(Object model, String type) Creates and returns a model handle of type type for model, which is not cached.
PModelHandle	createNewModel(String type) Creates a non-cached FList and a model handle of type type that wraps it.
boolean	doLogin(String name, String password) Uses login information to establish a connection with Portal and initialize BAS subsystem.
boolean	doLogin(String name, String password, String connectInfo) Uses login information to establish a connection with Portal and initialize BAS subsystem.
void	doLogout() Logs out of the Portal server, and closes the connection to it.
void	errorMsg(Component parent, String msg, boolean fromRes) Displays an error dialog with the passed-in message.
void	errorMsg(Component parent, String msg, Object[] args) Displays an error dialog with the passed-in message.
void	errorMsg(Component parent, String msg, String helpID, boolean fromRes) Displays an error dialog with the passed-in message.
int	errorMsg(Component parent, String msg, String title, Object[] options, int errType) Displays an error dialog with the passed-in message and given dialog type with given set of button options
String	getClassToInstantiate(String className) Used to determine if a class you are dynamically instantiating has been subclassed by the user.
PortalContext	getContext()
oracle.help.CSHManager	getCSHManager() Returns a CSHManager object, should one be needed.
oracle.help.library.helpset.HelpSet	getDefaultBook() Returns a HelpSet object, should one be needed.
abstract Properties	getDefaultProperties() Gets the default properties, including properties that are specified in the applet's "param" spec.
oracle.help.Help	getHelpObj() Returns a Help object, should one be needed.
abstract Component	getMainPane() Retrieves the lowest accessable view for this application.
Object	getModelField(PModelHandle modl, String desc) Gets the contents of a specific field of a model.
boolean	getPermissionFor(String componentName) Gets permission to use a component.
String	getResource(String base, String tag) Gets a specific resource.
ResourceBundle	getResources() Gets the applet resources.
PRestriction	getRestrictionOn(String fieldSpec) Gets restriction for a field.
abstract PBAServer	getServer() Gets a reference to the PBAServer implementation.
Properties	getUserPreferences()
boolean	init(PortalContext ctx) Initialize BAS subsystem using an existing PortalContext.
void	initHelp() Initializes the help system.
void	invokeInThread(Runnable toRun) Runs a task in a thread-pool managed thread.
void	invokeInThread(Runnable toRun, int relPriority) Runs a task in a thread-pool managed thread in priority order.
boolean	isConnectedToInfranet() Deprecated.
protected boolean	lastChanceLogin() Called to establish an RMI connection to the BAS server for this client While this used to also be associated with logging in to Portal, that is no longer required.
ImageIcon	loadImageIcon(String name) Loads an ImageIcon from a supplied location string.
ImageIcon	loadImageIcon(URL loc) Loads an ImageIcon from a supplied URL.
void	logRemote(String src, String msg) Serves as a debug feature.
void	mergeHelp(Properties props) Dynamically merges helpsets in the specified Properties in tags of the form: "subhelp.X" where X starts at 0 and increments by 1.
void	registerApp(String appName, Locale locale, Object data) Registers the application with the server.
void	registerComponent(PRemoteComponent comp, String controllerClass) Deprecated.
void	registerHelpButton(Component button, String helpID) Enables help for help buttons, generally in dialog boxes.
void	registerHelpIDFor(Component comp, String helpID) Registers a help ID to enable context-sensitive help for a component.
void	releaseContext(PortalContext ctx)
void	saveUserPreferences() Save user preferences Properties object to PIN_FLD_USER_PREFS field in /service/admin_client.
void	setModelField(PModelHandle modl, String desc, Object val) Sets the value of a field in a model.
void	setPropertyURL(URL newProps) Sets the URL of the property file to use.
void	setPropertyURL(URL newProps, String res) Sets the URL of the property file to use and the new resource file.
void	setUserPreferences(Properties userPrefs) Deprecated. Don't pass a Properties object explicitly. Use saveUserPreferences() instead and have this class manage the preferences.
void	unregisterComponent(PRemoteComponent comp)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RESKEY

protected static final String RESKEY

See Also:

Constant Field Values

mResources

protected ResourceBundle mResources

mConnection

protected PInfranetConnection mConnection

mBAServer

protected PBAServer mBAServer

mDefaults

protected Properties mDefaults

mHelpSet

protected oracle.help.library.helpset.HelpSet mHelpSet

mHelp

protected oracle.help.Help mHelp

mCSHManager

protected oracle.help.CSHManager mCSHManager

mPool

protected ThreadPool mPool

Constructor Detail

PClientServices

public PClientServices()

Method Detail

createModelHandle

public static PModelHandle createModelHandle(Object model,
                                             String type)

Creates and returns a model handle of type type for model, which is not cached. Although the model is not cached, the returned handle can still be passed to lookupModel() of the object cache to get back model. However, the recommended method for getting a non-cached model from a handle is PModelHandle.getModel().

Parameters:

model - a non-null object to be wrapped in a handle

type - the string representation of the object type

Returns:

A model handle that wraps model.

Throws:

IllegalArgumentException - if model is null

See Also:

#createNewModel, PModelHandle

getMainPane

public abstract Component getMainPane()

Retrieves the lowest accessable view for this application. This view is instance-specific; at build time, it won't be able to return anything. For applications, PClientServices returns a frame. For applets, PClientServices returns either the applet panel or, if the "window" param is set to "frame" in the source HTML document, an external frame.

Returns:

A component.

See Also:

PAppletServices, PBuilderServices, PApplicationServices

init

public boolean init(PortalContext ctx)

Initialize BAS subsystem using an existing PortalContext. This method may be used as an alternative to doLogin(). See class comment for additional details.

Parameters:

ctx - PortalContext that has already been connected to Portal. This PortalContext should no longer be used once it's been used to initialize BAS--it gets reset to its default state and looses its connection to Portal.

doLogin

public boolean doLogin(String name,
                       String password)

Uses login information to establish a connection with Portal and initialize BAS subsystem. This method may be used as an alternative to init(). Call this before loading controls. See class comment for additional details.

Parameters:

name - the user's login name

password - the user's password

Returns:

True if login succeeds; false if it fails.

doLogin

public boolean doLogin(String name,
                       String password,
                       String connectInfo)

Uses login information to establish a connection with Portal and initialize BAS subsystem. This method may be used as an alternative to init(). Call this before loading controls. See class comment for additional details.

Parameters:

name - the user's login name

password - the user's password

connectInfo - a String that contains connection information in URL format, for example, protocol://host:port

Returns:

True if login succeeds, false if it fails.

connect

public boolean connect(String name,
                       String password,
                       String connectInfo)
                throws RemoteException

Uses login information to establish a connection with Portal and initialize BAS subsystem. This method may be used as an alternative to init(). Call this before loading controls. See class comment for additional details. This is similar to doLogin the only difference being that this will throw a Remote Exception

Parameters:

name - the user's login name

password - the user's password

connectInfo - a String that contains connection information in URL format, for example, protocol://host:port

Returns:

True if login succeeds, false if it fails.

Throws:

RemoteException

doLogout

public void doLogout()

Logs out of the Portal server, and closes the connection to it.

getContext

public PortalContext getContext()

releaseContext

public void releaseContext(PortalContext ctx)

isConnectedToInfranet

public boolean isConnectedToInfranet()

Deprecated.

Checks for an open context. Usually called from an applet to see whether a login is needed.

Returns:

True if login occurred; false otherwise.

getPermissionFor

public boolean getPermissionFor(String componentName)

Gets permission to use a component.

Parameters:

componentName - the name of the component to test

Returns:

True if use is permitted; false otherwise.

getRestrictionOn

public PRestriction getRestrictionOn(String fieldSpec)

Gets restriction for a field.

Parameters:

fieldSpec - the field's specification

Returns:

An object that describes the restrictions.

getUserPreferences

public Properties getUserPreferences()

Returns:

the Properties object containing the user's preferences Gets the user's UI preferences. Only valid after a successful login.

saveUserPreferences

public void saveUserPreferences()

Save user preferences Properties object to PIN_FLD_USER_PREFS field in /service/admin_client. Saves the object managed by this class that is retrieved using getUserPreferences() method. Always use this preferred method to save user prefs. Saves user preferences to PIN_FLD_USER_PREFS field in /service/admin_client. Saves the object managed by this class that is retrieved using getUserPreferences() method. Always use this preferred method to save user preferences.

setUserPreferences

public void setUserPreferences(Properties userPrefs)

Deprecated. Don't pass a Properties object explicitly. Use saveUserPreferences() instead and have this class manage the preferences.

Save preferences Properties object to PIN_FLD_USER_PREFS field in /service/admin_client.

Parameters:

A - non-null Properties object containing the users preferences.

getResources

public ResourceBundle getResources()

Gets the applet resources. The resource file name can be set in the web page "param" spec. Usually called by Portal components.

Returns:

A ResourceBundle object.

addResourceBundle

public void addResourceBundle(String res)

Adds resources to the internal stack. Resources added with this call go on top of the internal resource state, so they are used in preference to what is already there.

Parameters:

res - a String that contains the resource bundle name

getResource

public String getResource(String base,
                          String tag)

Gets a specific resource. If not present, the resource tag is returned. This lets users specify strings that are shown directly, then replaced by real resources without having to change the code.

Parameters:

base - the resource base string. Usually specified as a property of a PAppComponent

tag - the resource name tag. This is appended to the base resource name, separated by a dot (.) and used to find a a resource. If not found, it is looked for alone (not appended to the base name), and if still not found, it is returned itself.

Returns:

The resource base string or the resource name tag.

initHelp

public void initHelp()

Initializes the help system. This is called by the applet or other services object during initialization.

mergeHelp

public void mergeHelp(Properties props)
               throws oracle.help.library.helpset.HelpSetParseException

Dynamically merges helpsets in the specified Properties in tags of the form: "subhelp.X" where X starts at 0 and increments by 1.

Parameters:

props - the property file to look in

Throws:

oracle.help.library.helpset.HelpSetParseException - thrown for helpset errors

getCSHManager

public oracle.help.CSHManager getCSHManager()

Returns a CSHManager object, should one be needed.

Returns:

A CSHManager object.

getDefaultBook

public oracle.help.library.helpset.HelpSet getDefaultBook()

Returns a HelpSet object, should one be needed.

Returns:

A HelpSet object.

getHelpObj

public oracle.help.Help getHelpObj()

Returns a Help object, should one be needed.

Returns:

A Help object.

registerHelpIDFor

public void registerHelpIDFor(Component comp,
                              String helpID)

Registers a help ID to enable context-sensitive help for a component. This should be called by all components for themselves, and for any embedded components for which context-sensitive help is provided.

Parameters:

comp - the component to register help for

helpID - the context help identifier

registerHelpButton

public void registerHelpButton(Component button,
                               String helpID)
                        throws IllegalArgumentException

Enables help for help buttons, generally in dialog boxes. This adds an action listener, so no other action is needed for the help button to work.

Parameters:

button - the help button to enable

helpID - the help ID to associate with the button

Throws:

IllegalArgumentException - thrown if the button is not java.awt.Button or javax.swing.AbstractButton (or a derivitive of either)

registerApp

public void registerApp(String appName,
                        Locale locale,
                        Object data)
                 throws RemoteException

Registers the application with the server. This gives the server-side components access to the application name and client locale.

Parameters:

appName - the application name

locale - the client's locale

data - other application-specific data

Throws:

RemoteException - thrown for errors

registerComponent

public void registerComponent(PRemoteComponent comp,
                              String controllerClass)
                       throws RemoteException

Deprecated.

Registers an Portal component with the server. This initializes the server-side logic. Usually called by Portal components.

Parameters:

comp - the Portal component implementation object

controllerClass - the name of the controller class for this component

Throws:

RemoteException - thrown for errors

unregisterComponent

public void unregisterComponent(PRemoteComponent comp)
                         throws RemoteException

Throws:

RemoteException

createController

public PControllerBean createController(String controllerClass)
                                 throws RemoteException

Registers an Portal component with the server. This initializes the server-side logic. Usually called by Portal components. This method will look through global properties to determine if that class has been overridden.If overridden, you'll get back the instance of the fully qualified class name of the subclass. If not, you'll get back the instance of the same class name passed in.
The property lookup will use the name of the class passed in with ".subclass" tacked on. So to override the class com.portal.Foo a customer would create a property entry as follows
com.portal.Foo.subclass=com.mypkg.Bar


Primarily intended to be used internally.

Parameters:

controllerClass - The name of the controller class for this component

Returns:

A new PControllerBean object.

Throws:

RemoteException - RemoteException thrown for errors

getDefaultProperties

public abstract Properties getDefaultProperties()

Gets the default properties, including properties that are specified in the applet's "param" spec.

Returns:

A Properties object.

errorMsg

public void errorMsg(Component parent,
                     String msg,
                     Object[] args)

Displays an error dialog with the passed-in message.

Parameters:

parent - the Component that triggered the message

msg - the error message tag; loads message from the resource file

args - an argument list with which to format msg

errorMsg

public void errorMsg(Component parent,
                     String msg,
                     boolean fromRes)

Displays an error dialog with the passed-in message.

Parameters:

parent - the Component that triggered the message

msg - the error message to display

fromRes -

errorMsg

public void errorMsg(Component parent,
                     String msg,
                     String helpID,
                     boolean fromRes)

Displays an error dialog with the passed-in message.

Parameters:

parent - the Component that triggered the message

msg - the error message to display

helpID - the context help identifier

fromRes -

errorMsg

public int errorMsg(Component parent,
                    String msg,
                    String title,
                    Object[] options,
                    int errType)

Displays an error dialog with the passed-in message and given dialog type with given set of button options

Parameters:

parent - the Component that triggered the message

msg - the error message to display

title - the title of error dialog

options - button options for error dialog

errType - type of dialog -1 : Plain Dialog 0 : Error Dialog 1 : Information Dialog 2 : Warning Dialog 3 : Question Dialog

Returns:

an integer indicating the option selected by the user

confirmationMsg

public int confirmationMsg(String msg)

Display a confirmation dialog containing the specified message and 2 choices for the user (YES or NO). The Yes button is selected by default.

Parameters:

msg - The confirmation message to display

msg - The confirmation message to display

Returns:

One of JOptionPane.YES_OPTION, JOptionPane.NO_OPTION, or JOptionPane.CLOSED_OPTION if the user cancel's the dialog Display a confirmation dialog containing the specified message and 2 choices for the user (YES or NO). The Yes button is selected by default.

confirmationMsg

public int confirmationMsg(String msg,
                           int def)

Display a confirmation dialog containing the specified message, default title and 2 choices for the user (YES or NO).

Parameters:

msg - The confirmation message to display

int - The default button. Use JOptionPane.YES_OPTION or JOptionPane.NO_OPTION

Returns:

One of JOptionPane.YES_OPTION, JOptionPane.NO_OPTION, or JOptionPane.CLOSED_OPTION if the user cancel's the dialog

confirmationMsg

public int confirmationMsg(String msg,
                           String title)

Display a confirmation dialog containing the specified message, title and 2 choices for the user (YES or NO). The Yes button is selected by default.

Parameters:

msg - The confirmation message to display

int - The default button. Use JOptionPane.YES_OPTION or JOptionPane.NO_OPTION

Returns:

One of JOptionPane.YES_OPTION, JOptionPane.NO_OPTION, or JOptionPane.CLOSED_OPTION if the user cancel's the dialog

confirmationMsg

public int confirmationMsg(String msg,
                           String title,
                           int def)

Display a confirmation dialog containing the specified message, title and 2 choices for the user (YES or NO).

Parameters:

msg - The confirmation message to display

title - The title of the confirmation dialog

int - The default button. Use JOptionPane.YES_OPTION or JOptionPane.NO_OPTION

Returns:

One of JOptionPane.YES_OPTION, JOptionPane.NO_OPTION, or JOptionPane.CLOSED_OPTION if the user cancel's the dialog

createNewModel

public PModelHandle createNewModel(String type)
                            throws RemoteException

Creates a non-cached FList and a model handle of type type that wraps it. If type is not null, empty, or PModelHandle.UNTYPED, a Poid of that type and id -1 is inserted into the FList, which is the model of the returned handle. Although the model is not cached, the handle can still be passed to lookupModel() of the object cache to get back the FList. However, the recommended method for getting a non-cached model from a handle is PModelHandle.getModel().

Parameters:

type - the string representation of an object type

Returns:

A model handle of type type that wraps an FList.

Throws:

RemoteException

See Also:

#createModelHandle, PModelHandle

logRemote

public void logRemote(String src,
                      String msg)

Serves as a debug feature. Creates an entry in the server log.

Parameters:

src - a String that defines the message source

msg - a message to log

getModelField

public Object getModelField(PModelHandle modl,
                            String desc)
                     throws RemoteException

Gets the contents of a specific field of a model.

Parameters:

modl - the model to access

desc - a description of the field needed

Returns:

The field value

Throws:

RemoteException - thrown for all problems, including the absence of the requested field in the specified model

setModelField

public void setModelField(PModelHandle modl,
                          String desc,
                          Object val)
                   throws RemoteException

Sets the value of a field in a model.

Parameters:

modl - the model to set a field in

desc - a description of the field to set

val - the new field's value

Throws:

RemoteException - thrown for all errors

setPropertyURL

public void setPropertyURL(URL newProps)

Sets the URL of the property file to use.

Parameters:

newProps - the new property file location

setPropertyURL

public void setPropertyURL(URL newProps,
                           String res)

Sets the URL of the property file to use and the new resource file.

Parameters:

newProps - the new property file location

res - the resource file location override in properties

loadImageIcon

public ImageIcon loadImageIcon(URL loc)

Loads an ImageIcon from a supplied URL.

Parameters:

loc - the URL for the image data

Returns:

A new ImageIcon.

loadImageIcon

public ImageIcon loadImageIcon(String name)

Loads an ImageIcon from a supplied location string.

Parameters:

name - the file name of the image data. Assumes that this file is located with other Java resources, so the name should be package relative, for example, "myImage.gif" or "com/portal/myapp/myImage.gif"

Returns:

A new ImageIcon.

createClientException

public PInfranetException createClientException(EBufException ebuf)

createClass

public Object createClass(String className)
                   throws ClassNotFoundException

Used to dynamically create instances of Customer Center beans and drilldowns and provide the ability for customers to override them. Specify the fully qualified class name for the Class you wish to create. This method will look through global properties to determine if that class has been overridden. If overridden, you'll get back an instance of the customized Class. If not, you'll get back an instance of the Class you have requested.

The property lookup will use the name of the class passed in with ".subclass" tacked on. So to override the class com.portal.Foo a customer would create a property entry as follows
com.portal.Foo.subclass=com.mypkg.Bar


Primarily intended to be used internally.

Parameters:

className - The class you want to dynamically instantiate

Throws:

ClassNotFoundException

createDialogClass

public Object createDialogClass(String className,
                                boolean isModal,
                                String title)
                         throws ClassNotFoundException

Throws:

ClassNotFoundException

getClassToInstantiate

public String getClassToInstantiate(String className)

Used to determine if a class you are dynamically instantiating has been subclassed by the user. This method will look through global properties to determine if that class has been overridden. If overridden, you'll get back the fully qualified class name of the subclass. If not, you'll get back the same class name passed in.

The property lookup will use the name of the class passed in with ".subclass" tacked on. So to override the class com.portal.Foo a customer would create a property entry as follows
com.portal.Foo.subclass=com.mypkg.Bar


Primarily intended to be used internally.

Parameters:

className - The class you want to dynamically instantiate

invokeInThread

public void invokeInThread(Runnable toRun)

Runs a task in a thread-pool managed thread.

Parameters:

toRun - the task to run

invokeInThread

public void invokeInThread(Runnable toRun,
                           int relPriority)

Runs a task in a thread-pool managed thread in priority order.

Parameters:

toRun - the task to run

relPriority - the relative priority of the task. Can be +1 to +4 to run at higher priority than normal, and -1 to -4 for lower priority.

lastChanceLogin

protected boolean lastChanceLogin()
                           throws RemoteException

Called to establish an RMI connection to the BAS server for this client While this used to also be associated with logging in to Portal, that is no longer required.

Returns:

True if a connection is established; false otherwise.

Throws:

RemoteException - thrown for errors

getServer

public abstract PBAServer getServer()

Gets a reference to the PBAServer implementation.

Returns:

A stub to the BAS server.