OSID Specifications
osid package
Version 3.0.0
Release Candidate Preview

The OsidForm is the vehicle used to create and update objects. The form is a container for data to be sent to an update or create method of a session. Applications should persist their own data until a form is successfully submitted in an update or create transaction.

The form may provide some feedback as to the validity of certain data updates before the update transaction is issued to the correspodning session but a successful modification of the form is not a guarantee of success for the update transaction. A consumer may elect to perform all updates within a single update transaction or break up a large update intio smaller units. The tradeoff is the granularity of error feedback vs. the performance gain of a single transaction.

OsidForms are Identifiable. The Id of the OsidForm is used to uniquely identify the update or create transaction and not that of the object being updated. Currently, it is not necessary to have these Ids persisted.

As with all aspects of the OSIDs, nulls cannot be used. Methods to clear values are also defined in the form.

A new OsidForm should be acquired for each transaction upon an OsidObject. Forms should not be reused from one object to another even if the supplied data is the same as the forms may encapsulate data specific to the object requested. Example of changing a display name and a color defined in a color interface extension:

                     ObjectForm form = session.getObjectFormForUpdate(objectId);
                     form.setDisplayName("new name");
                     ColorForm recordForm = form.getFormRecord(colorRecordType);
                     session.updateObject(objectId, form);

Tests if this form is for an update operation.

Returnboolean true if this form is for an update operation, false if for a create operation
CompliancemandatoryThis method must be implemented.

Gets a default locale for DisplayTexts when a locale is not specified.

Returnosid.locale.Localethe default locale
CompliancemandatoryThis method must be implemented.

Gets a list of locales for available DisplayText translations that can be performed using this form.

Returnosid.locale.LocaleLista list of available locales or an empty list if no translation operations are available
CompliancemandatoryThis method must be implemented.

Specifies a language and script type for DisplayText fields in this form. Setting a locale to something other than the default locale may affect the Metadata in this form.

If multiple locales are available for managing translations, the Metadata indicates the fields are unset as they may be returning a defeult value based on the default locale.

Parametersosid.type.TypelanguageTypethe language type
osid.type.TypescriptTypethe script type
ErrorsNULL_ARGUMENT languageType or scriptType is null
UNSUPPORTED languageType and scriptType not available from getLocales()
CompliancemandatoryThis method must be implemented.

Gets the metadata for the comment corresponding to this form submission. The comment is used for describing the nature of the change to the corresponding object for the purposes of logging and auditing.

Returnosid.Metadatametadata for the comment
CompliancemandatoryThis method must be implemented.

Sets a comment.

Parametersstringcommentthe new comment
ErrorsINVALID_ARGUMENT comment is invalid
NO_ACCESS Metadata.isReadonly() is true
NULL_ARGUMENT comment is null
CompliancemandatoryThis method must be implemented.

Tests if ths form is in a valid state for submission. A form is valid if all required data has been supplied compliant with any constraints.

Returnboolean false if there is a known error in this form, true otherwise
ErrorsOPERATION_FAILEDattempt to perform validation failed
CompliancemandatoryThis method must be implemented.

Gets text messages corresponding to additional instructions to pass form validation.

Returnosid.locale.DisplayText[]a list of messages
CompliancemandatoryThis method must be implemented.

Gets a list of metadata for the elements in this form which are not valid.

Returnosid.Metadata[]invalid metadata
CompliancemandatoryThis method must be implemented.