com.sage.accpac.sm
Class View

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

@NotThreadSafe
public class View
extends java.lang.Object

Represents an Accpac view
An object of this class can be created directly by an application (possibly by sub-classing) or it can be obtained from the Program or DBLink object's openView method.
Objects of this class are not thread-safe.
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.
After calling a method the application should check that the program's error stack is still clear. The view may very well add information to the call stack and still return success. If a method returns a SuccessLevel then if the level is Success there should not be any errors on the program's stack (but that is not guaranteed). If it returns Warning then the caller should check the program's error stack.

Thread safety

Thread-unsafe. Actually I am unsure. It is probably safe to access an instance from two threads but it will almost certainly lead to confusion and not be what is wanted. You should apply suitable synchronization to prevent confusion.

Nested Class Summary

static class	View.FilterOrigin Specifies the origin from where a filter should be applied
static class	View.OpenDirectives Indicates the method to be used when opening a view.
static class	View.OpenModes The set of values that can be used to make the mode passed when opening a view.
static class	View.Protocol Protocols
static class	View.RecordGenerateMode The mode passed to recordGenerate(com.sage.accpac.sm.View.RecordGenerateMode)
static class	View.ReferentialIntegrity Indicates the referential integrity setting of a view
static class	View.RotoType Indicates the type of a view.
static class	View.Security Security values which indicate the functionality the user is permitted to access on the view.
static class	View.SystemAccess Indicates the current access mode of a view

Constructor Summary

View(DBLink parent, java.lang.String rid)
Constructs an instance of the View class for the given roto id on the given link.

View(DBLink parent, java.lang.String rid, int modes, int prefetch, int directives)
Constructs an instance of the View class for the given roto id on the given link using the given mode, directives and prefetch.

View(Program program, java.lang.String rid)
Simple constructor based on Program

View(Program program, java.lang.String rid, int modes, int prefetch, int directives)
constructor based on Program

Method Summary

void	addNotificationListener(NotificationListener l) Add the given listener.
void	autocompose(View... views) composes the supplied list of views against this view, passing them in the correct order.
java.lang.Object[]	blkGet(int... fieldIDs) obtain the values of several fields
void	blkPut(boolean verify, int[] fieldIDs, java.lang.Object[] values) Change the field values of multiple fields
void	browse(java.lang.String filter, boolean isAscending) Starts a query and establishes the direction for subsequent calls that fetch records from the view.
void	cancel() cancels any unsaved changes in the view's revision list.
void	compose(View... views) composes the supplied list of views against this view.
static void	createTables(DBLink link, java.lang.String rid) Create the view's tables on the link's current database connection
static void	createTables(Program program, java.lang.String rid) Create the view's tables on the program's current database connections
void	delete() Deletes the current record from the database
void	dispose() Closes the view and releases all resources used by the object.
static void	dropTables(DBLink link, java.lang.String rid) Drop the view's tables on the link's current database connection
static void	dropTables(Program program, java.lang.String rid) Drop the view's tables on the program's current database connections
void	filterDelete(java.lang.String filter) Deletes the set of records that satisfy the supplied filter, including all children.
void	filterSelect(java.lang.String filter, boolean isAscending, int order, View.FilterOrigin origin) Starts a query and establishes the direction for subsequent calls that fetch records from the view.
protected void	finalize() overrides the finalize method of object so that the dispose gets called if it hasn't already
java.lang.Object	get(int fieldIndex) Gets the value of the field with the given index
java.lang.Object	get(java.lang.String fieldName) Gets the value of the field with the given name
java.util.List<java.lang.String>	getComposites() Gets a list of IDs of the views that the caller may explicitly compose.
java.lang.String[]	getDefiningKeyValues(int key) gets the values of the fields that define the current record relative to its header.
java.lang.String	getDescription() Description of the view
boolean	getDirty() Indicates whether the current record is dirty.
java.lang.String	getETag() gets the Edit Tag for the record.
boolean	getExists() Indicates whether the current primary key field values identify an existing record in the database
ViewFields	getFields() Gets the collection of fields for the view.
int	getFilterCount(java.lang.String filter) Gets the number of records in the view that match the filter
boolean	getHasUnpostedRevisions() Gets a value indicating whether there are unposted revisions in the view
boolean	getInstanceNoncascading() Reserved - Gets the Noncascading mode flag
boolean	getInstanceNonheritable() Gets whether the composite views implicitly opened by the current view inherit the additional parameters of the current view when it was opened.
int	getInstancePrefetch() Gets the number of records fetched at a time, if the view was opened read-only
int	getInstanceProtocol() Gets the view's protocol
boolean	getInstanceRawPut() Reserved
boolean	getInstanceReadOnly() gets whether the view is opened in readonly mode
boolean	getInstanceUnrevisioned() Gets whether revisioning is suppressed.
boolean	getInstanceUnValidated() Gets whether validation is suppressed.
ViewKeys	getKeys() get the collection of keys
int	getOrder() gets the current order or key number.
DBLink	getParent()
Program	getProgram() Gets the Program under which this View object is.
View.ReferentialIntegrity	getReferentialIntegrity() gets the current referential integrity flag of the view
View.Security	getSecuritySettings() Gets the View.Security settings that list the access rights the current user has on the view.
View.SystemAccess	getSystemAccess() gets the current system access mode of the view
java.util.Date	getTemplateDate()
java.lang.String	getTemplateVersion()
View.RotoType	getType() Gets the view type
java.lang.String	getViewID() Gets the view ID of the current view.
boolean	goBottom() goes to the bottom (last) record defined by the current query.
boolean	goNext() goes to the next record defined by the current query.
boolean	goPrev() goes to the previous record defined by the current query.
boolean	goTop() goes to the top (first) record defined by the current query.
void	insert() Inserts the current record into the database.
boolean	isNotification() Returns true if and only if the view instance was created with the ability to handle notifications.
void	post() Posts unsaved changes to the view.
void	post(ThreadEventListener listener) Performs view-specific posting on a separate thread
int	process() Performs view-specific processing
int	process(MeterEventListener meterListener) Performs view-specific processing which may raise a meter, providing a listener for the meter.
void	process(ThreadEventListener listener) Performs view-specific processing on a separate thread
void	putDefiningKeyValues(java.lang.String[] values, int key) sets the values of the fields that define the current record relative to its header.
boolean	read(boolean lockRecord) Locates and retrieves the record in the view according to the primary key field values of the current record.
void	recordClear() Blanks, zeroes or defaults the fields in the view
void	recordGenerate(View.RecordGenerateMode mode) Generate a unique nonexistent key, and blanks, zeroes or defaults the remaining fields in the view.
void	refreshSchema() informs the view that the caller has reason to suppose that the schema has changed, in particular the list of fields and keys.
void	removeNotificationListener(NotificationListener l) Remove the given listener.
void	revisionCancel(int level) Rolls back any pending changes to the specified revision level
boolean	revisionExists(int level) Checks whether the current record exists within the specified revision level
void	revisionPost(int level) Commits any changes to the specified revision level
boolean	revisionUnposted(int level) Checks whether the specified revision level has unposted changes
int	set(int field, java.lang.Object value) Sets the given field value without verification To set a field value with verification either use blkPut on the view or setValue on the field itself.
int	set(java.lang.String field, java.lang.Object value) Sets the given field value without verification.
void	setETag(java.lang.String tag) Sets the Edit Tag for the record.
void	setOrder(int order) Sets the current selected key on the view.
void	setReferentialIntegrity(View.ReferentialIntegrity value) sets the current referential integrity flag of the view
void	setSystemAccess(View.SystemAccess value) sets the current system access mode of the view
static void	shutdownExecutor()
boolean	supportsETag() Returns true if and only if the view supports ETags.
void	tableEmpty() Deletes all records in the database table in the fastest way possible
void	unlock() Unlocks a record previously locked by fetch or read
void	update() Updates the current record into the database.
boolean	verify() Validates the field values of the current record

Methods inherited from class java.lang.Object

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

Constructor Detail

View

public View(DBLink parent,
            java.lang.String rid,
            int modes,
            int prefetch,
            int directives)

Constructs an instance of the View class for the given roto id on the given link using the given mode, directives and prefetch.

Call dispose() when finished with the instance.

Parameters:

parent - the DBLink on which the view is opened.

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

See Also:

dispose(), View.OpenDirectives, View.OpenModes

View

public View(Program program,
            java.lang.String rid,
            int modes,
            int prefetch,
            int directives)

constructor based on Program

Call dispose() when finished with the instance.

Parameters:

program - the Program on which the view is opened.

rid - the roto id (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.

See Also:

dispose(), View.OpenDirectives, View.OpenModes

View

public View(DBLink parent,
            java.lang.String rid)

Constructs an instance of the View class for the given roto id on the given link.

The instance is constructed with default modes, directives and prefetch count.

Call dispose() when finished with the instance.

Parameters:

parent - the link on which the view is opened.

rid - the roto id (e.g. BK0001) of the view. This must be six characters long once trimmed.

See Also:

dispose()

View

public View(Program program,
            java.lang.String rid)

Simple constructor based on Program

Call dispose() when finished with the instance.

Parameters:

program - the Program on which the view is opened.

rid - the roto id (e.g. BK0001) of the view. This must be six characters long once trimmed.

See Also:

dispose()

Method Detail

dispose

public void dispose()

Closes the view and releases all resources used by the object. Do not call any methods after calling this.

addNotificationListener

public void addNotificationListener(NotificationListener l)

Add the given listener.
For the listener to receive events the view must also have been created with the InstanceNotify directive specified (e.g. using the extended constructor).

Parameters:

l - the NotificationListener to be added

Throws:

java.lang.IllegalStateException - if InstanceNotify was not specified when the view was constructed.

See Also:

removeNotificationListener(com.sage.accpac.sm.NotificationListener), NotificationListener

autocompose

public void autocompose(View... views)

composes the supplied list of views against this view, passing them in the correct order.
This will handle many compositions. However if the composite list contains duplicates use the normal compose function.

Examples

OE0520 has a compositeNames list of OE0500, OE0680, OE0180, OE0740, OE0526 and OE0522.

Using an array:

 View oe0520 = s.getView("OE0520");
 Views[] va = new Views[2];
 va[0] = s.getView("OE0180");
 va[2] = s.getView("OE0500");
 oe0520.compose(va);
 

Using var-args:

 View oe0520 = s.getView("OE0520");
 View oe0500 = s.getView("OE0500");
 View oe0180 = s.getView("OE0180");
 oe0520.compose(oe180, oe0500);
 

Parameters:

views - var-args list of or array of Views to be composed against this view. It is permissible to provide more views than are needed; the excess will be ignored.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

java.lang.IllegalArgumentException - if the argument is a null reference or the list is in some other way unacceptable.

ViewException - if there is some problem raised by the underlying views.

See Also:

getComposites, viewCompose

blkGet

public java.lang.Object[] blkGet(int... fieldIDs)

obtain the values of several fields

This behaves equivalently to multiple calls to get(int).

Parameters:

fieldIDs - variable length list or array of the ids of the fields to be fetched

Returns:

an array of objects containing the field values in the order specified

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

See Also:

get by numeric id, get by field name

blkPut

public void blkPut(boolean verify,
                   int[] fieldIDs,
                   java.lang.Object[] values)

Change the field values of multiple fields

Parameters:

verify - specifies whether the values should be verified at this stage

fieldIDs - the ids of the fields

values - the values. There must be at least as many as there are fieldIDs

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

java.lang.IllegalArgumentException - if there are fewer values than fieldIDs

UncheckedCharacterCodingException - if there is a conversion error. It will be a InvalidCharacterException if one of the inputs is a string that contains a character that cannot map to the character set of the session. It will be a MalformedInputException if one of the inputs is a string that is actually not a valid string (for example contains a trailing character without its leading character)

StringTooLongException - if one of the objects passed in will not fit in the number of bytes specified by its type

See Also:

set(int, Object)

browse

public void browse(java.lang.String filter,
                   boolean isAscending)

Starts a query and establishes the direction for subsequent calls that fetch records from the view.

Parameters:

filter - string containing the filter expression that restricts the records that will be retrieved.

isAscending - boolean value indicating whether subsequent records will be fetched in ascending or descending order. Calling browse does not change the ordering of records being fetched from the view. To control the ordering, use the setOrder() method to select a key.

Throws:

UncheckedCharacterCodingException - if there is a conversion error. It will be a InvalidCharacterException if the filter contains a character that cannot map to the character set of the session. It will be a MalformedInputException if the filter is actually not a valid string (for example contains a trailing character without its leading character)

java.lang.NullPointerException - if dispose() has been called on the view.

See Also:

filterSelect(String, boolean, int, FilterOrigin), #fetch(boolean), #filterFetch(boolean), goNext(), goPrev()

cancel

public void cancel()

cancels any unsaved changes in the view's revision list.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

compose

public void compose(View... views)

composes the supplied list of views against this view.

Examples

OE0520 has a compositeNames list of OE0500, OE0680, OE0180, OE0740, OE0526 and OE0522.

Using an array:

 View oe0520 = s.getView("OE0520");
 Views[] va = new Views[3];
 va[0] = s.getView("OE0500");
 va[1] = null;
 va[2] = s.getView("OE0180");
 oe0520.compose(va);
 

Using var-args:

 View oe0520 = s.getView("OE0520");
 View oe0500 = s.getView("OE0500");
 View oe0180 = s.getView("OE0180");
 oe0520.compose(oe0500, null, oe0180);
 

But Not:

DO NOT DO THIS; the second argument should be a third argument.

 View oe0520 = s.getView("OE0520");
 View oe0500 = s.getView("OE0500");
 View oe0180 = s.getView("OE0180");
 oe0520.compose(oe0500, oe0180);
 

Parameters:

views - var-args list of or array of Views to be composed against this view. The views in the list/array must be in the same order as the list returned by getComposites() with null references used as placeholders for those views that are not being provided. The trailing null references may be excluded. It is permissible to provide more views than are needed; the excess will be ignored.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

java.lang.IllegalArgumentException - if the argument is a null reference or the list is in some other way unacceptable.

ViewException - if there is some problem raised by the underlying views.

See Also:

getComposites, viewCompose

createTables

public static void createTables(DBLink link,
                                java.lang.String rid)

Create the view's tables on the link's current database connection

Parameters:

link - the link on which to create the tables

rid - the Roto Id of the view whose tables are to be created

createTables

public static void createTables(Program program,
                                java.lang.String rid)

Create the view's tables on the program's current database connections

Parameters:

program - the program on which to create the tables. If the view is not one of the standard Sage Accpac views and is a view on the system database then use the link-based overload.

rid - the Roto Id of the view whose tables are to be created

delete

public void delete()

Deletes the current record from the database

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

dropTables

public static void dropTables(DBLink link,
                              java.lang.String rid)

Drop the view's tables on the link's current database connection

Parameters:

link - the link on which to drop the tables

rid - the Roto Id of the view whose tables are to be dropped

dropTables

public static void dropTables(Program program,
                              java.lang.String rid)

Drop the view's tables on the program's current database connections

Parameters:

program - the program on which to drop the tables. If the view is not one of the standard Sage Accpac views and is a view on the system database then use the link-based overload.

rid - the Roto Id of the view whose tables are to be dropped

filterDelete

public void filterDelete(java.lang.String filter)

Deletes the set of records that satisfy the supplied filter, including all children.

Parameters:

filter - the filter to be applied. If the filter is a null reference or an empty or blank string this corresponds to matching all records.

Throws:

UncheckedCharacterCodingException - if there is a conversion error. It will be a InvalidCharacterException if the filter contains a character that cannot map to the character set of the session. It will be a MalformedInputException if the filter is actually not a valid string (for example contains a trailing character without its leading character)

filterSelect

public void filterSelect(java.lang.String filter,
                         boolean isAscending,
                         int order,
                         View.FilterOrigin origin)

Starts a query and establishes the direction for subsequent calls that fetch records from the view.

Parameters:

filter - A filter that restricts the records that will be retrieved.

isAscending - Indicates whether subsequent records will be fetched in ascending or descending order.

order - The key index to select on the view.

origin - The range of records the filter would affect.

Throws:

UncheckedCharacterCodingException - if there is a conversion error. It will be a InvalidCharacterException if the filter contains a character that cannot map to the character set of the session. It will be a DamagedStringException if the filter is actually not a valid string (for example contains a trailing character without its leading character)

get

public java.lang.Object get(int fieldIndex)

Gets the value of the field with the given index

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

See Also:

blkGet to get several fields in one operation

get

public java.lang.Object get(java.lang.String fieldName)

Gets the value of the field with the given name

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

See Also:

blkGet to get several fields in one operation

getComposites

public java.util.List<java.lang.String> getComposites()

Gets a list of IDs of the views that the caller may explicitly compose.

Returns:

an unmodifiable list of strings containing the roto IDs of the views that may be composed, in the order that they must be passed to compose.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

See Also:

compose(View...)

getDescription

public java.lang.String getDescription()

Description of the view

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

getDirty

public boolean getDirty()

Indicates whether the current record is dirty. A record is dirty if any of the field values were modified by the application since the record was last saved.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

supportsETag

public boolean supportsETag()

Returns true if and only if the view supports ETags. If the view does not support ETags then calling getETag() or setETag(java.lang.String) will result in an OperationNotSupportedException.

Returns:

true if the view supports the ETag calls and false otherwise.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

getETag

public java.lang.String getETag()

gets the Edit Tag for the record.

Returns:

the ETag as a String

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

java.lang.UnsupportedOperationException - if the view does not support ETags (i.e. if supportsETag() returns false)

See Also:

supportsETag(), setETag(String)

getExists

public boolean getExists()

Indicates whether the current primary key field values identify an existing record in the database

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

getFields

public ViewFields getFields()

Gets the collection of fields for the view.

Note that the returned reference will become obsolete if refreshSchema() is called.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

See Also:

refreshSchema()

getFilterCount

public int getFilterCount(java.lang.String filter)

Gets the number of records in the view that match the filter

Throws:

UncheckedCharacterCodingException - if there is a conversion error. It will be a InvalidCharacterException if the filter contains a character that cannot map to the character set of the session. It will be a DamagedStringException if the filter is actually not a valid string (for example contains a trailing character without its leading character)

getHasUnpostedRevisions

public boolean getHasUnpostedRevisions()

Gets a value indicating whether there are unposted revisions in the view

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

getDefiningKeyValues

public java.lang.String[] getDefiningKeyValues(int key)

gets the values of the fields that define the current record relative to its header.

A view can have a header view, a view that is a parent to this view. For example the header of a batch entry is the batch itself, and the header of an order detail line is the order itself. When putting data to the key fields there is generally no need to put to those fields that are references to the parent and indeed for some protocols doing so might result in an error.

Normally the header/detail relationship is defined by the primary key (key 0) but on some occasions there may be more than one header/detail relationship.

Parameters:

key - the key that defines the header/detail relationship.

Returns:

an array of Strings containing the fields in the order they appear in the key.

See Also:

putDefiningKeyValues(java.lang.String[], int)

putDefiningKeyValues

public void putDefiningKeyValues(java.lang.String[] values,
                                 int key)

sets the values of the fields that define the current record relative to its header.

A view can have a header view, a view that is a parent to this view. For example the header of a batch entry is the batch itself, and the header of an order detail line is the order itself. When putting data to the key fields there is generally no need to put to those fields that are references to the parent and indeed for some protocols doing so might result in an error.

Normally the header/detail relationship is defined by the primary key (key 0) but on some occasions there may be more than one header/detail relationship.

Parameters:

values - an array of Strings containing all the fields in the order they appear in the key. The leading ones may be checked against the header but will not be set. The defining ones will be set.

key - the key that defines the header/detail relationship.

Throws:

UncheckedCharacterCodingException - if one of the values was not a valid String of could not be encoded in the view's character set

BufferOverflowException - if one of the values was too large for the field

See Also:

getDefiningKeyValues(int)

getInstanceNoncascading

public boolean getInstanceNoncascading()

Reserved - Gets the Noncascading mode flag

getInstanceNonheritable

public boolean getInstanceNonheritable()

Gets whether the composite views implicitly opened by the current view inherit the additional parameters of the current view when it was opened.

getInstancePrefetch

public int getInstancePrefetch()

Gets the number of records fetched at a time, if the view was opened read-only

getInstanceProtocol

public int getInstanceProtocol()

Gets the view's protocol

Returns:

the view's protocol which will be a combination of the values of View.Protocol.

getInstanceRawPut

public boolean getInstanceRawPut()

Reserved

getInstanceReadOnly

public boolean getInstanceReadOnly()

gets whether the view is opened in readonly mode

getInstanceUnrevisioned

public boolean getInstanceUnrevisioned()

Gets whether revisioning is suppressed.

getInstanceUnValidated

public boolean getInstanceUnValidated()

Gets whether validation is suppressed.

getKeys

public ViewKeys getKeys()

get the collection of keys

Note that the returned reference will become obsolete if refreshSchema() is called.

Returns:

the list of keys.

See Also:

refreshSchema()

getOrder

public int getOrder()

gets the current order or key number.

Returns:

the current order or key number

See Also:

setOrder(int), filterSelect(String, boolean, int, FilterOrigin)

getParent

public DBLink getParent()

getProgram

public Program getProgram()

Gets the Program under which this View object is.

Returns:

the Program under which thie View is found.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

getReferentialIntegrity

public View.ReferentialIntegrity getReferentialIntegrity()

gets the current referential integrity flag of the view

getSecuritySettings

public View.Security getSecuritySettings()

Gets the View.Security settings that list the access rights the current user has on the view.

Returns:

a View.Security value that is the combination of the access rights the user has on the view.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

getSystemAccess

public View.SystemAccess getSystemAccess()

gets the current system access mode of the view

getTemplateDate

public java.util.Date getTemplateDate()

getTemplateVersion

public java.lang.String getTemplateVersion()

getType

public View.RotoType getType()

Gets the view type

getViewID

public java.lang.String getViewID()

Gets the view ID of the current view.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

goBottom

public boolean goBottom()

goes to the bottom (last) record defined by the current query. The bottom record is the one with no next record. See goNext() for more details.

Returns:

true if a record was found.

goNext

public boolean goNext()

goes to the next record defined by the current query.

The caller will have set up the query by a call to filterSelect(java.lang.String, boolean, int, com.sage.accpac.sm.View.FilterOrigin) or browse(java.lang.String, boolean), possibly combined with setOrder(int). The query expresses:

• which records are to be included, through the filter argument
• the order of the records, through the order and ascending arguments. Currently the system only supports the records being sorted all-ascending or all-descending.

Immediately following either a call to browse or filterSelect(...FilterOrigin.FromOrigin) a call to this method (or #fetch or #filterFetch) will return the record identified by the current primary key fields if it exists, or the next record if there is no record identified by the current primary key fields, or will return false if there is no such next record.

Immediately, in this context, means before any call to one of the navigation methods:

• fetch
• filterFetch
• goNext
• goPrev
• goTop
• goBottom

If there has been a call to one of the navigation methods then a call to this method will return the next record from the one identified by the current primary key values.

Note that this means although it is legal to jump around the set of records the results will not be quite what was expected unless a call to browse occurs at each jump, to signal that the current record is to be included.

For example:

 view.filterSelect(myFilter, true, 0, FilterOrigin.FromStart);
 while (view.goNext())
 {
    processRecord(view);
 }
 

Returns:

true if a record was found.

goPrev

public boolean goPrev()

goes to the previous record defined by the current query. See goNext() for more details.

Returns:

true if a record was found.

goTop

public boolean goTop()

goes to the top (first) record defined by the current query. The top record is the one with no previous record. See goNext() for more details.

Returns:

true if a record was found.

insert

public void insert()

Inserts the current record into the database.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

isNotification

public boolean isNotification()

Returns true if and only if the view instance was created with the ability to handle notifications. This happens if the View.OpenDirectives.InstanceNotify directive was specified in the constructor.

post

public void post()

Posts unsaved changes to the view. This method is used primarily on header views where the call has a cascading effect that causes its detail views to update the unposted revisions.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

post

public void post(ThreadEventListener listener)

Performs view-specific posting on a separate thread

process

public int process()

Performs view-specific processing

Returns:

the view return code. Unlike most methods this one does not throw an exception of view errors.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

process

public void process(ThreadEventListener listener)

Performs view-specific processing on a separate thread

process

public int process(MeterEventListener meterListener)

Performs view-specific processing which may raise a meter, providing a listener for the meter.

read

public boolean read(boolean lockRecord)

Locates and retrieves the record in the view according to the primary key field values of the current record.

Parameters:

lockRecord - boolean value indicating if the record should be locked after it is retrieved.

Returns:

whether the intended record exists in the view and is retrieved.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

recordClear

public void recordClear()

Blanks, zeroes or defaults the fields in the view

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

recordGenerate

public void recordGenerate(View.RecordGenerateMode mode)

Generate a unique nonexistent key, and blanks, zeroes or defaults the remaining fields in the view.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

removeNotificationListener

public void removeNotificationListener(NotificationListener l)

Remove the given listener.

Parameters:

l - the listener to remove.

See Also:

removeNotificationListener(com.sage.accpac.sm.NotificationListener), NotificationListener

refreshSchema

public void refreshSchema()

informs the view that the caller has reason to suppose that the schema has changed, in particular the list of fields and keys.

The view will refresh its information. Any outstanding references to fields etc. are the concern of the caller.

See Also:

getKeys(), getFields()

revisionCancel

public void revisionCancel(int level)

Rolls back any pending changes to the specified revision level

Parameters:

level - Revision level

revisionExists

public boolean revisionExists(int level)

Checks whether the current record exists within the specified revision level

Parameters:

level - Revision level

revisionPost

public void revisionPost(int level)

Commits any changes to the specified revision level

Parameters:

level - Revision level

revisionUnposted

public boolean revisionUnposted(int level)

Checks whether the specified revision level has unposted changes

Parameters:

level - Revision level

set

public int set(java.lang.String field,
               java.lang.Object value)

Sets the given field value without verification.

To set a field value with verification either use blkPut on the view or setValue on the field itself.

Parameters:

field - the name of the field to put

value - the value to put to the field

Throws:

UncheckedCharacterCodingException - if the value was or was interpreted as a String and either it was not a valid String of could not be encoded in the view's character set

BufferOverflowException - if the value was too large for the field

java.lang.NullPointerException - if dispose() has been called on the view.

See Also:

blkPut to put several fields in one calls

set

public int set(int field,
               java.lang.Object value)

Sets the given field value without verification To set a field value with verification either use blkPut on the view or setValue on the field itself.

Parameters:

field - the name of the field to put

value - the value to put to the field

Throws:

UncheckedCharacterCodingException - if the value was or was interpreted as a String and either it was not a valid String of could not be encoded in the view's character set

BufferOverflowException - if the value was too large for the field

java.lang.NullPointerException - if dispose() has been called on the view.

See Also:

blkPut to put several fields in one calls

setETag

public void setETag(java.lang.String tag)

Sets the Edit Tag for the record. This is a very unusual thing to do!

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

java.lang.UnsupportedOperationException - if the view does not support ETags (i.e. if supportsETag() returns false)

StringTooLongException - if the tag is longer than permitted

InvalidCharacterException - if the tag contains non-ASCII or non-printable characters.

java.lang.IllegalArgumentException - if the tag is null or otherwise malformed.

setOrder

public void setOrder(int order)

Sets the current selected key on the view. Changing the selected key affects the order in which records are fetched from the view.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

See Also:

getOrder(), filterSelect(String, boolean, int, FilterOrigin)

setReferentialIntegrity

public void setReferentialIntegrity(View.ReferentialIntegrity value)

sets the current referential integrity flag of the view

setSystemAccess

public void setSystemAccess(View.SystemAccess value)

sets the current system access mode of the view

tableEmpty

public void tableEmpty()

Deletes all records in the database table in the fastest way possible

update

public void update()

Updates the current record into the database.

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

unlock

public void unlock()

Unlocks a record previously locked by fetch or read

Throws:

java.lang.NullPointerException - if dispose() has been called on the view.

verify

public boolean verify()

Validates the field values of the current record

Returns:

true if the record is valid and false if it is not valid. Note that even if the method returns true the caller should still check to see if there is any additional information on the program's error stack that should be displayed to the user.

shutdownExecutor

public static void shutdownExecutor()

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