Java Server API

This topic describes functions that the java server provides for Jython.

All of these functions are defined in the Java-class de.planta.server.webservice.WebHqlQueryHandler (name is for historic reasons), used like this:

PY

from de.planta.server.webservice import WebHqlQueryHandler

dbhandler = WebHqlQueryHandler()
dbhandler.setJythonUser('R41')

Pojo Interface

For regular customizing you should use the functions described in the JythonUtilitiesPojoApi topic, as those wrap the following functions and make them easier to work with.

Method	Parameter(s)	Return Value	Comment
getPojo	entity: String, the entity name of the Pojo class that is queried uuid: String, the uuid of the queried object	returns a Pojo-Object (subclass of de.planta.server.hibernate.pojo.HibernatePojoClass)	Returns the Pojo-object identified by entity name & UUID, or None if not found
createPojo	entity: String, the entity name of the Pojo class that is created	returns a new Pojo-Object (subclass of de.planta.server.hibernate.pojo.HibernatePojoClass)	Creates a new Pojo-object of the desired class
savePojo	pojo: HibernatePojoClass which is to be modified	returns boolean indicating if save-operation was successful can raise de.planta.server.exception.PlantaEventException for errors happening inside Events, or general Exception for other exceptions in Java/Native code	Updates all properties of the given Pojo that have been changed, and saves it into the database.
deletePojo	pojo: HibernatePojoClass which is to be deleted	returns boolean indicating if delete-operation was successful can raise de.planta.server.exception.PlantaEventException for errors happening inside Events, or general Exception for other exceptions in Java/Native code	Deletes the given Pojo from the database.

Pojo Class

Method

Parameters

Return Value

Comment

pojoOriginalValues

Returns a Java map which contains a string which identifies the DI (entityname) and original values as an object

Identical to DtpRecord.get_changed_dis

The functions that refer to a DI have a string parameter which identifies the appropriate DI. This is an entity name from DT412, not the DI number.

hasPropertyBeenUpdated

String: propertyName

bool: True if DI has changed its value, but not been saved yet, false otherwise

Identical to Dataitem.has_been_updated

pojoOriginalPropertyValue

String: propertyName

Original value of the DI (from database, before it was changed), data type differs based on the DIs DB type

Identical to Dataitem.get_original_value

HQL Interface

For regular customizing you should use the functions described in the JythonUtilitiesDatabaseApi topic, as those wrap the following functions and make them easier to work with.

Method	Parameter(s)	Return Value	Comment
hqlQuery	hql: String, a HQL-statement parameters: HashMap which holds parameters of the HQL-statement (optional parameter; can be omitted if the statement has no parameters)	returns as a list of objects in the form of a list of sublists	Is intended for Select-statements returning data from the database. For the usage of HQL-parameters, see Bindevariablen in Statements
hqlModify	hql: String, a HQL-statement parameters: HashMap which holds parameters of the HQL-statement (optional parameter; can be omitted if the statement has no parameters)	returns the number of modified records as integer	Is intended for Insert/Update/Delete-Statements into the database. For the usage of HQL-parameters, see Bindevariablen in Statements
hqlStatementUsesLiterals	hql: String, a HQL-Statement	bool: True if the statement contains Literals	For the significance of literals, see Literale in Statements
enableLiteralsSQLTransformation			For the significance of this, see Literale in Statements
disableLiteralsSQLTransformation			For the significance of this, see Literale in Statements

Generic functions

Function	Parameter(s)	Return Value	Comment
setJythonUser	user: String, User-Name		Remembers this user name for this Jython-session
getJythonUser		String: A User-name	Returns User-name that was remembered by setJythonUser
uiMessageBox	caption: String, caption of Message Box message String, text of Message Box icon: String, OLE-id of Message Icon buttons: List of Strings which name the buttons in Message Box) input_no Int, number of text fields in Message Box	can raise de.planta.server.exception.SessionNotFoundException	This displays a message, identical to ppms.ui_message_box, with the exception that the parameter blocking does not exist, as message boxes that are displayed by Jython are NEVER blocking. The first 2 parameters are mandatory, the rest can be omitted. This only works if the Jython-session is associated to a client-session. If not, a SessionNotFoundException is raised.
uiMessageBoxId	id: String, the ID of the dialog message	can raise de.planta.server.exception.SessionNotFoundException	This displays a message, identical to ppms.ui_message_id, which is never blocking in this case. This only works if the Jython-session is associated to a client-session. If not, a SessionNotFoundException is raised.
getAutoID	diId: String, id of a DI with Auto-Ids (e.g. "001400")	String: The next auto-number for this DI (with current license) can raise ClassNotFoundException, AutoIdOverflowException	Returns the next auto-number for this DI, or None if di_id does not denote a di using auto-numbers
openModule	thread: Long, ID for a currently running session module: String, ID of the module to open dictionary: Hashmap<String, Object>, a dictionary containing variables for the module	boolean: Indicating if the module could be found and prepared can raise de.planta.server.exception.SessionNotFoundException, de.planta.server.exception.ModuleNotFoundException, de.planta.server.exception.ModuleDictionaryException	Prepares the module identified by module-ID to be opened in the Client-session identified by thread-id (if existing). Note: This is an asynchronous call, which means the openModule will finish before the module is actually opened. That's why the return value does not indicate whether opening of the module was successful, just whether a module & a thread with requested IDs exist After the module is opened, the new Python-callback-function on_web_load(Dictionary) is called with the parameters given to openModule. The parameter-dictionary supports parameters of type Boolean, String, Integer, Float, or lists thereof Should be used through the Jython function jython.server.module.open_module
getReturnValueForModule	thread: Long, ID for a currently running session module: String, ID of the module to open	Dictionary: The return value of on_web_load of the module which was called in this thread can raise de.planta.server.exception.SessionNotFoundException, de.planta.server.exception.ModuleDictionaryException	The return value is a dictionary of the same type as the dictionary of openModule. If the module has not been run yet, None is returned If the module has no method called on_web_load, or on_web_load does not return a value, an empty Dictionary is returned
getServerConfiguration	parameterList: String, list of parameter groups or parameters From S 39.5.37, semicolon, colon, comma or space can be used as separators	Dictionary: Returns the given parameters and their values	to get the configuration of the server
getServerParameter	parameter: String, name of a parameter	String: value of the parameter	to get a single parameter of the server

Events and Exit Control

With the following functions, you can temporarily disable (& re-enable) any Exit or Data Event in the running server.

This only applies to the current session. In other sessions, these exits & events are still enabled.

Note:

This does NOT change the (permanent) enabled property in the Event Data table. For an event to be executed, this field must be enabled (=1), AND the event must not be disabled by one of the following functions.

This affects all Data Events (excluding Timed Events), with the exception of some hard-coded events for license checking, which are always active.

Function	Parameter(s)	Comment
disableAllEvents		Temporarilly disables every Date-Event
enableAllEvents		Re-enables every Data-Event that has been temporarilly disabled by any function
disableEventsForTable	tableId: Integer	Temporarilly disables every Data-Event that is assigned to the given table
enableEventsForTable	tableId: Integer	Re-enables only those events that have temporarilly disabled for this table
disableEvent	eventUuid: String, the uuid of the event	Temporarilly disables the event identified by eventUuid
enableEvent	eventUuid: String, the uuid of the event	Re-enables the event identified by eventUuid

Basically the same functionality, but for old Native-Code-Exits, not for events

Function	Parameter(s)	Comment
disableAllExits		Temporarilly disables every Exit
enableAllExits		Re-enables every Exit that has been temporarilly disabled by any function
disableExit	exitId: Integer	Temporarilly disables the exit identified by exitId
enableExit	exitId: Integer	Re-enables the exits identified by exitId

Session Info

Helper functions to get informations about the current Java/Jython-session

Function	Parameter(s)	Return Value	Comment
getCurrentThreadId		Long: ThreadId	Returns the ThreadID of the current PlantaSession. Intended to use for functions like openModule, getSessionInfo, etc.
getActiveClientSessions		List of Long: ThreadIds	Returns a list with the ThreadIDs of all Client-Sessions that are currently open/active
getSessionUser	threadId: Long, ID of a session		To get the user that started a specific Client Session
getSessionInfo	threadId: Long, ID of a session		SessionInfo is a Java-class that holds various information about a session, including: SessionInfo.getUser()) <- That's identical to WebHqlQueryHandler.getSessionUser SessionInfo.getTimeStamp() <- Future functionality that's not really implemented yet; currently, always start time SessionInfo.getSessionUUID() <- A unique UUID for each SessionInfo, used to identify a record in DT 443. SessionInfo.getStartTime() SessionInfo.getEndTime() <- Always NULL if the session is still active; is the end-time of a historical session. Can be identified by its UUID. SessionInfo.getReason() <- Why a session was terminated: Error or clean shutdown. Can be identified by its UUID

Clientless Session

A clientless session is a special session that (like the name suggests) runs without GUI-client or webclient.

It is controlled by Jython-functions and identified /accessed by a unique (random) ID that the server assigns when it is created.

Function	Parameter(s)	Return Value	Comment
openClientlessSession	user: String, name of the user which starts this session (e.g. P20)	Unique ID of the new clientless session can raise de.planta.server.exception.UserNotFoundException	Starts the session. The session stays open until closeClientlessSession is called.
openModuleByClientlessId	clientlessSessionId: Int. The return value of openClientlessSession, to identify the session in question. module: String, ID of the module to open dictionary: Hashmap<String, Object>, a dictionary containing variables for the module	Returns boolean indicating if the module could be found and prepared can raise de.planta.server.exception.ClientlessSessionNotFoundException de.planta.server.exception.ModuleNotFoundException de.planta.server.exception.ModuleDictionaryException	This function is identical to openModule, with the only exception that it is called with clientless Id instead of thread-id. (see there for description of parameters and functionality). Therefor, it also executes the special python-event on_web_load.
getReturnValueForModuleByClientlessId	clientlessSessionId: Int. The return value of openClientlessSession, to identify the session in question. module: String, ID of the module to open	Dictionary: The return value of on_web_load of the module which was called in this thread can raise de.planta.server.exception.SessionNotFoundException, de.planta.server.exception.ModuleDictionaryException	Get the return value of on_web_load of module. This function is identical to getReturnValueForModule, with the only exception that it is called with clientless Id instead of thread-id. (see there for description of parameters and functionality).
closeClientlessSession	clientlessSessionId: Int. The ireturn value of openClientlessSession, to identify the session in question.	void can raise de.planta.server.exception.ClientlessSessionNotFoundException	Closes the session
openClientlessSession	user: String, name oft he user which starts this session (e.g. P20), module: String, ID of the module to open dictionary: Hashmap<String, Object>, a dictionary containing variables for the module	Unique ID of the new clientless session can raise de.planta.server.exception.UserNotFoundException de.planta.server.exception.ClientlessSessionNotFoundException de.planta.server.exception.ModuleNotFoundException de.planta.server.exception.ModuleDictionaryException	Opens a new clientless session and executes a module in it. Basically a convencience function, as calling it is is identical to new_id = openClientlessSession(user) openModuleByClientlessId(new_id, module_id, some_dictionary)
getThreadIdOfClientlessSession	int: Clientless Session-Id	Long: ThreadID can raise de.planta.server.exception.ClientlessSessionNotFoundException	The input Parameter is the DI of a Clientless session (the value that is returned by openClientlessSession and is used as the first parameter by the functions which handle clientlessSessions). Returns the threadID (Long-value) of this Clientless Session, which can be used for functions like openModule, getSessionInfo, etc.