com.sage.accpac.sm
Class Program

java.lang.Object
  com.sage.accpac.sm.Program

All Implemented Interfaces:

HasCompany, HasDispose, HasSecurity, IProgram, HasParams

@ThreadSafe
public class Program
extends java.lang.Object
implements IProgram

Represents an authenticated program with the Sage Accpac System Manager.
The caller must call the dispose method when finished with the object so that all its resources can be released. The caller must not call any other method on the object after calling dispose.

Thread safety

Thread-safe. However be aware that you may experience confusion since a Program is shared between many views etc. For example two threads may both cause information to be added to the error stack, so that when you access getErrors() the errors will be a mix from the two threads.

Field Summary

java.lang.Object

userData Deprecated.

Constructor Summary

Program(Session session, java.lang.String appID, java.lang.String programName, java.lang.String appVersion)
Complete constructor.

Method Summary

void	dispose() call this when the instance is no longer required, to free up resources.
protected void	finalize() overrides the finalize method of object so that the dispose gets called if it hasn't already
ActiveApplications	getActiveApplications() Gets the list of active applications on the program The list contains the applications for the current company; this value is cached so changes (e.g.
java.lang.String	getAppID() Gets the application ID of the current application.
java.lang.String	getAppVersion() Gets the version of the current application.
Company	getCompany() Gets a Company object that stores details of the company profile as set up in Common Services
java.io.File	getCompanyDirectory(java.lang.String area) returns a File that is the location where the given area can store its company-specific files.
java.util.List<java.lang.String>	getDisplayableIcons(java.lang.String appID, java.lang.String appVersion, java.util.List<Icon> iconsToCheckDisplay) get a non-null list of icons that are displayable based on the given application's icon display logic.
Errors	getErrors() Gets a reference to the program's errors collection.
FiscalCalendar	getFiscalCalendar() Gets a FiscalCalendar object that provides methods to access the fiscal calendar set up in the company.
java.lang.String[]	getInstalledReports(java.lang.String appID) Retrieves a list of reports installed in the system for the supplied application ID.
IPropertyBag	getIPropertyBag() Returns an IPropertyBag for the program's inherited menu
IPropertyBag	getIPropertyBag(java.lang.String menuID) Returns an IPropertyBag for the specified menu of the program
ISession	getISession() Gets the Program's session
Licenses	getLicenses() Get the list of licenses on the program The list contains the licenses presented at the time of the call; changes after this call are not reflected in the returned collection.
Meter	getMeter() Gets any meter anonymously attached to the Program
Multiuser	getMultiuser() Gets the Multiuser object that contains methods for controlling multi-user access.
java.lang.Object	getParam(java.lang.String viewID, int field) Retrieves a parameter stored in a view.
GettableByField	getParams(java.lang.String viewID) gets a GettableByField that exposes the parameters of the given view.
java.io.File	getProgramFilesDirectory(java.lang.String area) returns a File that is the location where the given area has stored its resource files.
java.lang.String	getProgramName() gets the program name (Roto ID) of the current application.
PropertyBag	getPropertyBag() Returns an PropertyBag for the program's inherited menu
PropertyBag	getPropertyBag(java.lang.String menuID) Returns an IPropertyBag for the specified menu of the program
java.lang.String	getRscString(java.lang.String pgmID, int strID) Gets the given string resource for the specified application.
Session	getSession() returns the Program's Session
java.io.File	getUserCompanyDirectory(java.lang.String area) returns a File that is the location where the given area can store its files that are specific to both a user and a company.
java.io.File	getUserDirectory(java.lang.String area) returns a File that is the location where the given area can store its user-specific files.
boolean	isPermitted(java.lang.String resource) returns whether or not the user is permitted to access the given security resource.
DBLink	openDBLink(DBLink.LinkType type, DBLink.LinkFlags flags) Creates a database link to the specified database.
IView	openIView(java.lang.String viewID) opens a view
IView	openIView(java.lang.String viewID, int modes, int prefetch, int directives) opens a view.
View	openView(java.lang.String viewID) opens a view.
View	openView(java.lang.String viewID, int modes, int prefetch, int directives) opens a view.
java.lang.Object[]	paramGet(java.lang.String viewID, int... fieldIDs) Retrieves a list of parameters stored in a view.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

userData

@Deprecated
public java.lang.Object userData

Deprecated.

A single hook where the application can hook data in.
This allows the application to preserve its own data merely by the Program continuing to exist.

Deprecated - Subclass the program

Constructor Detail

Program

public Program(Session session,
               java.lang.String appID,
               java.lang.String programName,
               java.lang.String appVersion)

Complete constructor.
This constructor starts a program against the given session.

Parameters:

session - the session under which this program is opened

appID - the application id of this Program

programName - the name by which this program is to be known

appVersion - the version of this application

Method Detail

dispose

public void dispose()

call this when the instance is no longer required, to free up resources. It is normal to throw NullPointerException if this has already been called.

Specified by:

dispose in interface HasDispose

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getActiveApplications

public ActiveApplications getActiveApplications()

Gets the list of active applications on the program
The list contains the applications for the current company; this value is cached so changes (e.g. activation etc.) after the first time this is called are not reflected in the returned collection.

Specified by:

getActiveApplications in interface IProgram

Returns:

an ActiveApplications listing the active applications

getLicenses

public Licenses getLicenses()

Get the list of licenses on the program
The list contains the licenses presented at the time of the call; changes after this call are not reflected in the returned collection.

Specified by:

getLicenses in interface IProgram

Returns:

the Licenses collection.

getAppID

public java.lang.String getAppID()

Gets the application ID of the current application. This is the application ID used to initialize the program.

Specified by:

getAppID in interface IProgram

Returns:

the application ID

getAppVersion

public java.lang.String getAppVersion()

Gets the version of the current application. This is the version used to initialize the program.

Specified by:

getAppVersion in interface IProgram

Returns:

the version of the current application

getCompany

public Company getCompany()

Gets a Company object that stores details of the company profile as set up in Common Services

The returned object represents the state at the time of this call.

Specified by:

getCompany in interface HasCompany

Returns:

a Company representing the company profile.

getCompanyDirectory

public java.io.File getCompanyDirectory(java.lang.String area)

returns a File that is the location where the given area can store its company-specific files.

The File returned is a directory that exists and is both readable and writable.

The caller may lay out the directory any way that it chooses.

For consistency if the caller has files that are specific to both a user and a company then use the IProgram.getUserCompanyDirectory(String).

Specified by:

getCompanyDirectory in interface IProgram

Parameters:

area - the area whose files are wanted. Remember to use consistent case for the area name since different operating systems may be case-sensitive.

Returns:

a File that is the location where the given area may store its company-specific files.

See Also:

IProgram.getUserCompanyDirectory(String), IProgram.getUserDirectory(String), IProgram.getProgramFilesDirectory(String)

getDisplayableIcons

public final java.util.List<java.lang.String> getDisplayableIcons(java.lang.String appID,
                                                                  java.lang.String appVersion,
                                                                  java.util.List<Icon> iconsToCheckDisplay)

get a non-null list of icons that are displayable based on the given application's icon display logic.

Specified by:

getDisplayableIcons in interface IProgram

Parameters:

appID - the application ID

appVersion - the application version

iconsToCheckDisplay - the list of icons to be checked whether they are displayable.

Returns:

a non-null list of displayable icon IDs.

getErrors

public Errors getErrors()

Gets a reference to the program's errors collection. Note that this returns a shared reference; the Errors collection can change in the background. It does not return the current list of errors.

Specified by:

getErrors in interface IProgram

Returns:

an Errors collection

See Also:

Errors

getFiscalCalendar

public FiscalCalendar getFiscalCalendar()

Gets a FiscalCalendar object that provides methods to access the fiscal calendar set up in the company.

Specified by:

getFiscalCalendar in interface IProgram

Returns:

a FiscalCalendar containing the company's fiscal calendar

getInstalledReports

public java.lang.String[] getInstalledReports(java.lang.String appID)

Retrieves a list of reports installed in the system for the supplied application ID.
This method only accepts the application ID, but not the version. The version of the application is automatically determined by the one activated for the current company.

Specified by:

getInstalledReports in interface IProgram

Parameters:

appID - Application ID.

Returns:

an array of report names installed in the system. Note that the report names do not include file paths.

getIPropertyBag

public IPropertyBag getIPropertyBag()

Returns an IPropertyBag for the program's inherited menu

Specified by:

getIPropertyBag in interface IProgram

Returns:

an IPropertyBag for the program's inherited menu

getIPropertyBag

public IPropertyBag getIPropertyBag(java.lang.String menuID)

Returns an IPropertyBag for the specified menu of the program

Specified by:

getIPropertyBag in interface IProgram

Parameters:

menuID - the menu ID of the particular property bag requested. If this is a null reference or a string of length zero then the inherited property bag will be selected.

Returns:

an IPropertyBag for the specified menu of the program

getISession

public ISession getISession()

Gets the Program's session

Specified by:

getISession in interface IProgram

Returns:

the ISession in which the program is running

getMeter

public Meter getMeter()

Gets any meter anonymously attached to the Program

Specified by:

getMeter in interface IProgram

Returns:

a Meter attached to the program, or null if there is none

getMultiuser

public Multiuser getMultiuser()

Gets the Multiuser object that contains methods for controlling multi-user access.

Specified by:

getMultiuser in interface IProgram

Returns:

a Multiuser for the program

getPropertyBag

public PropertyBag getPropertyBag()

Returns an PropertyBag for the program's inherited menu

Returns:

a PropertyBag for the program's inherited menu

getPropertyBag

public PropertyBag getPropertyBag(java.lang.String menuID)

Returns an IPropertyBag for the specified menu of the program

Parameters:

menuID - the menu ID of the particular property bag requested. If this is a null reference or a string of length zero then the inherited property bag will be selected.

Returns:

an IPropertyBag for the specified menu of the program

getProgramFilesDirectory

public java.io.File getProgramFilesDirectory(java.lang.String area)

returns a File that is the location where the given area has stored its resource files.

The File returned is a directory that exists and is at least readable.

Specified by:

getProgramFilesDirectory in interface IProgram

Parameters:

area - the area whose files are wanted. Remember to use consistent case for the area name since different operating systems may be case-sensitive.

Returns:

a File that is the location where the given area has stored its resource files.

See Also:

IProgram.getCompanyDirectory(String), IProgram.getUserDirectory(String), IProgram.getUserCompanyDirectory(String)

getProgramName

public java.lang.String getProgramName()

gets the program name (Roto ID) of the current application.

Specified by:

getProgramName in interface IProgram

Returns:

the program name (Roto ID) of the current application.

getRscString

public java.lang.String getRscString(java.lang.String pgmID,
                                     int strID)

Gets the given string resource for the specified application. This retrieves the requested string resource for the currently activated version of the application, using the program's current language.

Specified by:

getRscString in interface IProgram

Parameters:

pgmID - String containing the two-character application prefix of the application. The application prefix can be in lower or upper case.

strID - Numeric identifier of the particular text resource to fetch

Returns:

The requested string, if it can be obtained, and an empty string otherwise.

getSession

public Session getSession()

returns the Program's Session

Use getISession() instead

Returns:

the Program's Session

getUserCompanyDirectory

public java.io.File getUserCompanyDirectory(java.lang.String area)

returns a File that is the location where the given area can store its files that are specific to both a user and a company.

The File returned is a directory that exists and is both readable and writable.

The caller may lay out the directory any way that it chooses.

Specified by:

getUserCompanyDirectory in interface IProgram

Parameters:

area - the area whose files are wanted. Remember to use consistent case for the area name since different operating systems may be case-sensitive.

Returns:

a File that is the location where the given area may store its user-company-specific files.

See Also:

IProgram.getCompanyDirectory(String), IProgram.getUserDirectory(String), IProgram.getProgramFilesDirectory(String)

getUserDirectory

public java.io.File getUserDirectory(java.lang.String area)

returns a File that is the location where the given area can store its user-specific files.

The File returned is a directory that exists and is both readable and writable.

The caller may lay out the directory any way that it chooses.

For consistency if the caller has files that are specific to both a user and a company then use the IProgram.getUserCompanyDirectory(String).

Specified by:

getUserDirectory in interface IProgram

Parameters:

area - the area whose files are wanted. Remember to use consistent case for the area name since different operating systems may be case-sensitive.

Returns:

a File that is the location where the given area may store its company-specific files.

See Also:

IProgram.getCompanyDirectory(String), IProgram.getUserCompanyDirectory(String), IProgram.getProgramFilesDirectory(String)

isPermitted

public boolean isPermitted(java.lang.String resource)

returns whether or not the user is permitted to access the given security resource.

Specified by:

isPermitted in interface HasSecurity

Parameters:

resource - the name of the resource to be checked. This must consist of only ASCII printable characters and may be at most 10 characters long.

Returns:

true if and only if the user is permitted to access the given resource.

openDBLink

public DBLink openDBLink(DBLink.LinkType type,
                         DBLink.LinkFlags flags)

Creates a database link to the specified database. A database link can be created on the company database or the system database to which the signed on company is attached.
Remember to call dispose on the link when finished with it.

Specified by:

openDBLink in interface IProgram

Parameters:

type - specifies the type of database link to create.

flags - specified the type of access intended on the database link.

Returns:

a fresh DBLink object that represents the database.

openView

public View openView(java.lang.String viewID)

opens a view.

If the view is not one of the standard Sage Accpac views and is a view on the system database then use DBLink's openIView(...)

Specified by:

openView in interface IProgram

Parameters:

viewID - Roto ID of the view to open. The Roto ID is defined by the application.

Returns:

a view object that represents the view.

openIView

public IView openIView(java.lang.String viewID)

opens a view

If the view is not one of the standard Sage Accpac views and is a view on the system database then use DBLink's openIView(...)

Specified by:

openIView in interface IProgram

Parameters:

viewID - Roto ID of the view to open. The Roto ID is defined by the application.

Returns:

a view object that represents the view.

openIView

public IView openIView(java.lang.String viewID,
                       int modes,
                       int prefetch,
                       int directives)

opens a view.

If the view is not one of the standard Sage Accpac views and is a view on the system database then use DBLink's openView(...)

Specified by:

openIView in interface IProgram

Parameters:

viewID - the rotoid (e.g. BK0001) of the view. This must be six characters long once trimmed.

modes - an integer value containing a set of flags that control behavior. See View.OpenModes.

prefetch - the number of records to pre-fetch when the view is opened (0 to 63)

directives - specifies how the view should be used. See View.OpenDirectives.
If the view does not identify itself as a 4.2A or later template (either it identifies itself as earlier or it does not support the xxxVersionTemplate entry) then the InstanceOpen directive will be assumed.

Returns:

a view object that represents the view.

openView

public View openView(java.lang.String viewID,
                     int modes,
                     int prefetch,
                     int directives)

opens a view.

If the view is not one of the standard Sage Accpac views and is a view on the system database then use DBLink's openIView(...)

Specified by:

openView in interface IProgram

Parameters:

viewID - the rotoid (e.g. BK0001) of the view. This must be six characters long once trimmed.

modes - an integer value containing a set of flags that control behaviour. See View.OpenModes.

prefetch - the number of records to pre-fetch when the view is opened (0 to 63)

directives - specifies how the view should be used. See View.OpenDirectives.
If the view does not identify itself as a 4.2A or later template (either it identifies itself as earlier or it does not support the xxxVersionTemplate entry) then the InstanceOpen directive will be assumed.

Returns:

a view object that represents the view.

paramGet

public java.lang.Object[] paramGet(java.lang.String viewID,
                                   int... fieldIDs)

Retrieves a list of parameters stored in a view.

This method is applicable only to views that are designed to store parameters of an application. These views typically have one and only one record. Internally, this method opens the specified view, fetches the first record, and returns the values of the specified field IDs.

Specified by:

paramGet in interface HasParams

Parameters:

viewID - Roto ID of the view from which to retrieve the parameters

fieldIDs - a var-args list or array of field indexes of which parameters should be retrieved

Returns:

an array of parameter values read from the view. The parameter values returned in the array appears in the same order as the corresponding field IDs specified in the fieldIDs parameter.

getParam

public java.lang.Object getParam(java.lang.String viewID,
                                 int field)

Retrieves a parameter stored in a view.

This method is applicable only to views that are designed to store parameters of an application. These views typically have one and only one record. Internally, this method opens the specified view, fetches the first record, and returns the values of the specified field IDs.

Specified by:

getParam in interface HasParams

Parameters:

viewID - Roto ID of the view from which to retrieve the parameters

field - the field indexes of which parameter should be retrieved

Returns:

the values read from the view.

getParams

public GettableByField getParams(java.lang.String viewID)

gets a GettableByField that exposes the parameters of the given view.

Note that although the return value is a full GettableByField it can only be accessed by field indexes, not names

Specified by:

getParams in interface HasParams

Parameters:

viewID - the Roto ID of the view from which to retrieve the parameters

Returns:

a GettableByField that exposes the parameters by field index

finalize

protected void finalize()

overrides the finalize method of object so that the dispose gets called if it hasn't already

Overrides:

finalize in class java.lang.Object