How-to-Use the Web2c Toolkit
Author: R. Bacher, DESY/MCS
Last Update: December, 12th, 2011
Version: 6.0.x
Synoptic
Display Component Reference
Synoptic
Display Attribute Reference
fieldLength highIcon yMin
Synoptic Display Initialization File Specification
Synoptic Display Component Extension Interface
Archive Viewer Component Reference
Archive Viewer Attribute Reference
Archive Viewer Initialization File Specification
Gateway HTTP-Post API Reference
Gateway Configuration File Specification
Build, Deployment and Launching
Control System Device and Archive Access
[back]
The Web2c Synoptic Display is a configurable, browser-hosted, dynamic and interactive internet application. Each page [jpg] consists of various components listed in a corresponding configuration file [xml]. The page is updated at a rate as specified in the corresponding page configuration file. Clicking a Value (ValueList) component will display a 120-seconds history of the corresponding read-back value(s). Each page may contain another pages as embedded pages. The sections of the embedded pages must fit fully within the borders (browser window) of the superior page.
All users have to login prior to page download. Access will be granted only to registered and authenticated users. All open page have their own http session running on a web application server and do not interfere. Passive components such as trends or read-back values will be displayed to all users. Buttons, sliders, wheel switches and input fields will be displayed to authorized users (so-called experts and supervisors) only as specified in the corresponding page configuration file. In addition, buttons, sliders, wheel switches and input fields marked as super components will be visible for supervisors only. IP addresses are specified in the corresponding page configuration file the requesting IP address must coincide with one of the listed IP addresses to keep expert or supervisor privileges.
The Web2c Synoptic Display supports video. The image displayed by a video components is updated at the page update rate.
Each page is attached to a unique chat channel which can be collaboratively used by users with expert or supervisor privileges as specified in the corresponding page configuration file.
The pre-defined functionality of most Web2c Synoptic Display components can indiviually be overwritten and extended at run-time by user-defined extension classes (JAVA). The extensions must implement the corresponding Web2c Synoptic Display component extension interface.
The Web2c Archive Viewer is a configurable, browser-hosted, dynamic and interactive internet application. Each archive viewer page [jpg] is configured according to its corresponding configuration file [xml] specifying a set of archive data channels names. Data (maximal 3600 data points within the selected time interval) can be displayed graphically or as table of comma-separated values. The data plot allows to zoom in by clicking successively the left and right edge of the area of interest.
All users will have full access without passing a specific login procedure.
The archive viewer can be used in two modes. In the manual mode, the user can select the data channels through the data selector form. In the automatic mode, the data selector form is hidden and only the chart with pre-selected data channels and time interval is displayed automatically after page download.
The Web2c Synoptic Display Editor is a browser-hosted, dynamic and interactive internet application [jpg] to create, edit and save synoptic display configuration files. If minimized, the size of the drawing frame is one quarter of the actual size (1230px * 974px), and matches with the actual size, if maximized. A page consists of sections which must be positioned relatively to the left-top corner of the browser window. Each page may contain components which must be positioned relatively to the left-top corner of the corresponding sections. In addition, each page may contain another pages as embedded pages. The sections of the embedded pages must fit fully within the borders (browser window) of the superior page.
The Web2c Synoptic Display Editor has limited WYSIWYG functionality. Indicators, lists of indicators, animated images and static images are displayed as specified in the list of attributes of the corresponding component. Other element types such as buttons, sliders etc. are replaced by generic text labels. A page preview of a loaded synoptic display configuration file can be launched by clicking the "Page Preview" button.
Components already added to the drawing frame can be selected by mouse click. Clicking and dragging the lower right corner of a selected component resizes the component. The attribute list displays the attribute values of the selected component. Component attribute values can be modified by entering the corresponding text in the right column of the attribute list. Multiple entries (see expert, ipAddress, caption, legend, uri attribute etc.) have to be separated by ";" and entered as a single line. All attribute changes must be confirmed before selecting the next component.
All users have to login prior to page download. Access will be granted only to registered and authenticated users. Synoptic display configuration files can be saved to disk by authorized users (so-called experts) only as specified in the editor page configuration file.
The Web2c Messenger is a servlet process which can send messages to the following interfaces:
Twitter: The messenger configuration file ("messenger.xml") defines the tweets (status) which are published periodically. The file has to be located in the sub-directory "web2cToolkit/WebContent/userdocs". By default, the twitter service is disabled and must be enabled explicitly in the corresponding twitter profile file ("Web2cTwitterInit.xml") containing the twitter service credentials. The different tweets are sent one after another at intervals of 3 minutes and can be retrieved from the servlet.
SMTP (E-Mail / SMS): The servlet provides a form to write and send a plain text e-mail or SMS message. The SMTP profile file ("Web2cSMTPInit.xml") must contain the SMTP service credentials.
The Web2c Gateway is a servlet process which provides a HTTP-POST-based interface (XML- Syntax) to the control systems attached. The gateway configuration file ("gateway.xml") defines among other things which user is accepted as an expert and/or from which network address privileged actions can be performed.The file has to be located in the sub-directory "web2cToolkit/ WebContent/userdocs".
Implemented functionalities are:
Register: Establishes a single monitor or a list of control system monitors (i.e. periodically updated control system connections).
Update: Updates the read-back value(s) of a single or a list of control system monitors.
Execute: Sends a single write-request or a list of write-requests to the control system.
Guest login: Opens a Web2c gateway session (read-only). Does not require a login procedure.
Expert login: Opens a Web2c gateway session (read and write) with secure user authentication and authorization login procedure. The expert names have to be specified in the gateway.xml file hosted by the web server.
Logout: Closes a Web2c gateway session.
Alive check: Checks the alive-status of the servlet.
- Editing all initialization files and parameters
- Editing the user registry
- Displaying the servlet diagnostics pages
- Controlling garbage collection and Java Virtual Machine performance
- Controlling the debugging and logging settings
- Controlling the messenger services
- Controlling the auto-reporting service
[back]
Synoptic
Display Component Reference
Component
Description
Applicable Attributes
Remarks
toggles between two different images; highIcon is used if read-back value is above alarm threshold, otherwise lowIcon
alarmThreshold, blinking, blinkingEnabled, bounds, expertComponent, extensionManifest, highIcon, id, lowIcon, sound, soundEnabled, tooltipText, uri
click button
backgroundColor, blinking, blinkingEnabled, bounds, caption, color, condition, extensionManifest, fontSize, fontThickness, id, image, keepHistory, prompt, superComponent, tooltipText, uri
button actions pointing to a uri of form "http://...." are always visible independent of the user's role
condition: as many entries as wanted
uri: as many entries as required
chat form
alignment, backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, caption, color, expertComponent, fontSize, fontThickness, id, sound, soundEnabled, tooltipText
embedded Web2c Synoptic Display page
bounds, id, uri
plots data arrays versus index
bounds, caption, condition, expertComponent, extensionManifest, fontSize, function, id, legend, plotAxis, plotColor, plotOrder, plotType, tooltipText, uri, xLabel, xMax, xMin
uri: as many entries as data arrays
legend: as many entries as data arrays
condition: as many entries as wanted
yMin / yMax: as many entries as data arrays
static image
bounds, expertComponent, extensionManifest, id, tooltipText, uri
colored label; toggles between different label colors; a trueIcon is used if read-back value is equal to the corresponding trueValue, otherwise falseIcon
blinking, blinkingEnabled, border, borderColor, bounds, expertComponent, extensionManifest, falseIcon, id, sound, soundEnabled, tooltipText, trueIcon, trueValue, uri
single-column table of indicators with column header
blinking, blinkingEnabled, border, borderColor, bounds, expertComponent, extensionManifest, falseIcon, headerBackgroundColor, headerCaption, headerColor, id, sound, soundEnabled, tooltipText, trueIcon, trueValue, uri
uri: as many entries as table rows
input field for text or numbers
backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, caption, color, extensionManifest, fieldLength, fontSize, fontThickness, id, superComponent, tooltipText, uri
static label
alignment, backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, caption, color, expertComponent, extensionManifest, fontSize, fontThickness, id, tooltipText
single-column table of labels with column header
alignment, backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, caption, color, expertComponent, extensionManifest, fontSize, fontThickness, headerBackgroundColor, headerCaption, headerColor, id, tooltipText
caption: as many entries as table rows
Web2c Synoptic Display page
caption, exclusive, expert, debug, ipAddress, message, timeInterval, reconnect, soundEnabled, supervisor
expert: as many entries as expert names
supervisor: as many entries as supervisor names
ipAddress: as many entries as addresses
page section
backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, id, extensionManifest,
slider to enter a set value
backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, caption, color, extensionManifest, fontSize, fontThickness, id, maximum, minimum, tooltipText, uri
read-back text value
Note: Characters with an ASCII scan code less than 0x1f will be replaced by the space character (0x20)
alignment, backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, color, condition, expertComponent, extensionManifest, fontSize, fontThickness, id, scrollBar, sound, soundEnabled, superComponent, tooltipText, uri
condition: as many entries as wanted
single-column table of text values with column header
Note: Characters with an ASCII scan code less than 0x1f will be replaced by the space character (0x20)
alignment, backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, color, condition, expertComponent, extensionManifest, fontSize, fontThickness, headerBackgroundColor, headerCaption, headerColor, id, sound, soundEnabled, tooltipText, uri
uri: as many entries as table rows
condition: as many entries as wanted
news ticker
backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, color, expertComponent, extensionManifest, fontSize, fontThickness, id, offset, sound, soundEnabled, tooltipText, uri
time label
alignment, backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, color, fontSize, fontThickness, id, tooltipText
plots data arrays versus time
bounds, caption, condition, expertComponent, extensionManifest, fontSize, function, id, legend, plotAxis, plotColor, plotType, timeInterval, tooltipText, uri
uri: as many entries as data arrays
legend: as many entries as data arrays
condition: as many entries as wanted
yMin / yMax: as many entries as data arrays
read-back number value; toggles between two different caption colors; highColor is used if read-back value is above alarmThreshold, otherwise lowColor
alarmThreshold, alignment, backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, expertComponent, extensionManifest, fontSize, fontThickness, format, function, highColor, id, legend, lowColor, minLimit, sound, soundEnabled, tooltipText, uri
single-column table of number values with column header; toggles between two different caption colors; highColor is used if read-back value is above alarmThreshold, otherwise lowColor
alarmThreshold, alignment, backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, expertComponent, extensionManifest, fontSize, fontThickness, format, function, headerBackgroundColor, headerCaption, headerColor, highColor, id, legend, lowColor, minLimit, sound, soundEnabled, tooltipText, uri
uri: as many entries as table rows
legend: as many entries as data arrays
video viewer
alignment, backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, caption, color, expertComponent, extensionManifest, fontSize, fontThickness, id, tooltipText, uri
device to enter a set value
backgroundColor, blinking, blinkingEnabled, border, borderColor, bounds, caption, color, extensionManifest, fontSize, fontThickness, id, superComponent, tooltipText, uri
[back]
Synoptic
Display Attribute Reference
Attribute
Description
Value
Format
threshold value
any number
any number format (e.g. 3, 1.0)
text alignment mode
left, center, right
text string
background color value of component
black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, yellow
Note: the colors listed in the extended CSS color palette might not be supported by all browsers
text string
blinking effect, toggles between the specified colors
sound file name
text string:
- color1-color2
- color11-color12,color21-color22,color31-color32, .... (for list components, as many entries as list members)
indicates if blinking effect is enabled
yes: enabled
no: disabled
text string
border mode
none, thin, thick
text string
border color value of component
black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, yellow
Note: the colors listed in the extended CSS color palette might not be supported by all browsers
text string
all components (except Section, EmbeddedPage): position and size of the component, measured relatively to the section the component belongs to
Section: position and size, measured relatively to the page or embedded page the section belongs to
EmbeddedPage: position and size, measured relatively to the page the embedded page belongs to
x-position of left upper corner (px), y-position of left upper corner (px), x-position of right lower corner (px), y-position of right lower corner (px)
Note: x-position of right lower corner > x-position of right upper corner, y-position of right lower corner > y-position of right upper corner
four comma-separated integer numbers (e.g. 23,17,456,645)
text value (Page title, Button caption, Label caption, LabelList captions, Trend title, Histo title)
any text
text string or list of comma-separated text strings (see footnote 1 and footnote 2)
color value (Button caption, Label caption, LabelList captions, Ticker label caption, Time label caption)
black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, yellow
Note: the colors listed in the extended CSS color palette might not be supported by all browsers
text string
modifies graphical appearance of component if true
applicable for:
Text, TextList, Value, ValueList, Label, LabelList, Section, Button: color, backgroundColor, blinking, blinkingEnabled, fontSize, fontThickness, tooltipText
Histo, Trend: plotColor, tooltipText
string consisting of condition equation and style argument assignments
space-separated text string, e.g.
tine:///DESY2/GlobalsCollector/Keyword/ParticleTypeText()=Positronen color=orange backgroundColor=white
checks control system link availability prior to page load
yes: check is performed, error info is displayed
no: check is not performed, page is displayed, unavailable links are ignored
text string
read access is granted to the exclusive users only and not to any user
any text
text string (e.g. name)
expert name
optional: IP address; expert privilege granted only in case address is matching
(see ipAddress)
any text
(see ipAddress)
text string[(IP address)] (e.g. name, name(131.169.150.83))
(see ipAddress)
expertComponent
flag indicating whether a specific component is invisible for laymen
yes, no text string
extensionManifest
name of file containing the extension manifest
any text
text string
content of the manifest file:
<extension>
<extensionClass>extensionClassFullName</extensionClass> (e.g. de.desy.web2cToolkit.web2cExtensionDemo.Web2cExtensionDemo)
<guiComponentType>guiComponentType</guiComponentType> (e.g. Web2cTicker)
<guiDataSize>guiDataSize</guiDataSize> (e.g. 1)
<remoteCommandURI>remoteCommandURI</remoteCommandURI>
<monitorURI>monitorURI</monitorURI>
<receiverURI>receiverURI</receiverURI>
<actionURI>actionURI</actionURI>
</extension>
uri: as many entries whishedimage to be displayed if corresponding read-back value is not equal to trueValue
any valid image file name
file_name.mime_type (e.g. redicon.jpg)
input field length
>0: field written is filled up with spaces until length = input field length
0 or blank: field written is not filled up with spaces
decimal number
font size
tiny, small, medium, large, extraLarge, huge, extraHuge, gigantic
text string
font thickness
normal, bold
text string
display format (Value, ValueList)
any valid format value
0digit
ndigit, zero shows as absent
.decimal separator
-minus sign
Eseparates mantissa and exponent in scientific notation.
(e.g. nn0.00, 0.000E00)
mathematical function applied to data prior to data update
rms, ave, std, min, max, power, factor, offset, log: Value, ValueList, Histo, Trend
norm, ref: Histo, Trend
Note: the function specified is applied to all data channels listed in ValueList, Histo or Trend
rms([p]): RMS value of a data array, scaled by p (def = 1.0)
ave([p]): average value of a data array, scaled by p (def = 1.0)
min([p]): minimum value of a data array, scaled by p (def = 1.0)
max([p]): maximum value of a data array, scaled by p (def = 1.0)
std([p]): standard deviation value of a data array, scaled by p (def = 1.0)
power([p]): pth power of a value (def = 1.0)
factor([p]): multiplicative factor (def = 1.0)
offset([p]): offset of a value (def = 0.0)
log([p]): log10 of a value, scaled by p (def = 1.0)
norm([p]): data value normalized (%) to value of channel p (def = 1, first channel), data of channel p set to 100%
ref([p]): data value minus value of channel p (def = 1, first channel), data of channel p set to 0.0)
text string (e.g. rms(0.001)
background color (LabelList header, ValueList header, IndicatorList header)
black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, yellow
Note: the colors listed in the extended CSS color palette might not be supported by all browsers
text string
text value (LabelList header caption, ValueList header caption, IndicatorList header caption)
any text
text string or list of comma-separated text strings (see footnote 1 and footnote 2)
color value (LabelList header caption, ValueList header caption, IndicatorList header caption)
black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, yellow
Note: the colors listed in the extended CSS color palette might not be supported by all browsers
text string
caption color value used if read-back value is above alarmThreshold (Value caption, ValueList captions)
black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, yellow
Note: the colors listed in the extended CSS color palette might not be supported by all browsers
text string
image to be displayed if corresponding read-back value is above alarm threshold
any valid image file name
file_name.mime_type (e.g. redicon.jpg)
page-wide unique component identifier
Note: embedded pages may contain the same component identifiers
any text
text string
image to be displayed on button instead of caption text
any valid image file name
file_name.mime_type (e.g. redicon.jpg)
on-line status if a Web2c page requests another Web2c page
true = requesting page will remain continuously updated and logged in
false = requesting page will be cleared and logged out
text string
IP address
blank: layman privilege granted
not blank: expert / supervisor privilege granted only in case address is matching
text string
(e.g. 131.169.150.83, 131.169.150.*, 131.169.*.*, 131.*.*.*; *.*.*.*)
legend for plot trace
any text
text string or list of comma-separated text strings (see footnote 1 and footnote 2)
caption color value used if read-back value is below or equal to alarmThreshold (Value caption, ValueList captions)
black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, yellow
Note: the colors listed in the extended CSS color palette might not be supported by all browsers
text string
image to be displayed if corresponding read-back value is below alarm threshold
any valid image file name
file_name.mime_type (e.g. redicon.jpg)
minimal slider value
any number
text string
message to be displayed if server update is missing
any text; if blank, no message will be displayed
text string or list of comma-separated text strings (see footnote 1 and footnote 2)
will be suppressed if "reconnect" attribute is set true
maximal slider value
any number
text string
minimal reasonable value limit
any number
text string
time offset in milliseconds
any value (+: later, -: earlier)
text string
single- or multi-axis plot (Histo, Trend)
single, multi
text string
list of color values for plot traces (maximal 10 color values)
red, blue, magenta, green, darkRed, yellow, orange, cyan, darkGray, black or user-defined (R_G_B)
color1,color2, ...,color10 (e.g. yellow,red,blue,255_69_0)
index order
normal, invert
text string
plot mode (area below plot trace is color filled if areaPlot / areaTimePlot)
x-Axis = index: linePlot, areaPlot, barPlot (Histo)
x-Axis = time: lineTimePlot, areaTimePlot, barTimePlot (Histo)
linePlot, areaPlot (Trend)
text string
format and order of user entries in output window (Chat)
chat: name: user entry, last line = last entry
message: date name: user entry, first line = last entry
text string
page status after server start-up
true = automatic page reload after server start-up
false = no automatic page reload after server start-up
text string
horizontal and vertical scaling factors for page size
Note: does not affect border and font size
x-scale value, y-scale value
two comma-separated integer numbers (e.g. 1.234,1.367)
vertical scrollbar (Text)
yes = with scrollbar
no = without scrollbar
text string
sound effect, if supported by operating system
sound file name
text string (e.g. gong.wav)
indicates if sound effect is enabled
Note: if the page sound effect is disabled, sound is also disabled for all other components
yes: enabled
no: disabled
text string
flag indicating whether a specific component is visible only for
read component: experts and supervisors
write component: supervisors
yes, no
text string
supervisor name
optional: IP address; supervisor privilege granted only in case address is matching
(see ipAddress)
any text
(see ipAddress)
text string[(IP address)]
(e.g. name, name(131.169.150.83))
(see ipAddress)
interval for page update (Page), plot interval (Trend)
any number (seconds)
decimal number (e.g. 2, 3600)
component tooltip text
if blank, control system address description is displayed if applicable and available
any text
text string or list of comma-separated text strings (see footnote 1 and footnote 2)
list of images; an image is displayed if indicator read-back value is equal to corresponding trueValue
any list of valid image file names
file_name.mime_type (e.g. redicon.jpg), comma separated list
list of comparison values
any list of numbers
any number format (e.g. 3, 1.0), comma separated list
file name (EmbeddedPage), web link (Button), control system address string (AnimatedImage, Image, Button, Indicator, IndicatorList, Ticker, Trend, Histo, Value, ValueList) or action message to be processed by servlet (Text, Button)
any valid file name, web link, control system address string, video source address string or action message string
file://file_name.mime_type, e.g.
- file://embedded.xml
http://url_string, e.g.
- http://tine.desy.de
control_system_name://control_system_address, e.g.
- (read) tine:///context/server/device/property([from_index][;to_index])
- (write) tine:///context/server/device/property([par1])
- (read) doocs://facility/device/location/property()
- (write) doocs://facility/device/location/property([par1])
- (read) tango://host_ip_number/device/attribute()
- (write) tango://host_ip_number/device/command([par1])
- (read) epics://host_ip_number/channel_address()
- (write) epics://host_ip_number/channel_address([par1])
video_streaming_protocol://transmitter address, e.g.
- rtp://ip_number/port_number
- tine:///context/server/device/property
local://action_message, e.g.
- activityCounter, i.e. reads the activity counter (Text)
- login, i.e. displays login dialog for page currently loaded (Button) to switch from non-privileged to privileged user
- logout, i.e. closes the page (Button)
- superLogout, i.e. closes the page (Button)
- Note: button visible for supervisors only
- switchLanguage, i.e. reloads the page with the next available language_code (Button)
- replace(new_config_file_name.xml[;language_code]), i.e. replaces the page by the page specified (Button)
label for x-axis
any text
text string (see footnote 1)
maximum value of x-axis displayed, ignored if xMin = xMax
any value, any time-date string
text string (e.g. -24.0, 2009-05-17 15:37:22)
minimum value of x-axis displayed, ignored if xMin = xMax
any value, any time-date string
text string (e.g. -24.0, 2009-05-17 15:37:22)
maximum value of y-axis displayed, ignored if yMin = yMax
any value
text string (e.g. 0.0)
minimum value of y-axis displayed, ignored if yMin = yMax
any value
text string (e.g. 35.8)
Footnote 1: Special characters such as ",", "[", "]", greek characters or other symbols have to be entered via their corresponding decimal ASCII Code, e.g. for [ write ASCIIC(91).
Footnote 2: To use the multi-language feature, specify a list of text strings representing the text in different languages. Note the order in the list. The first list member corresponds to language code 0 (default: 0).
[back]
Synoptic Display Initialization File Specification
The login page of the Synoptic Display Viewer (and the Archive Viewer) can be customized according to the user’s wishes via the file “web2cInit.xml” read during servlet startup.
<config>
<salutation>header_text</salutation>
<earlyRegistering>configFile1</earlyRegistering>
<earlyRegistering>....</earlyRegistering>
<earlyRegistering>configFileN</earlyRegistering>
</config>
The field header_text contains the title displayed by the login page. If the file is missing or no salutation is supplied, the default title “Web2cToolkit: Framework for Web-based Controls Clients” will be displayed.
The field configFile contains the name of the file which is processed at servlet startup for early link registering.
[back]
Synoptic Display Component Extension Interface
Functionalities:
- Executes Web2c extension code
- Returns the execution status of the extension code (0, if successfully executed).
- Returns data to be visualized by the component's GUI (e.g. Web2cValue, if any) or data to be used to determine the data a to be visualized by the component's GUI (e.g. Web2cValue, if any)
- Returns commands issued by user action at the components's GUI to be executed by the control systems attached (e.g. Web2cButton, if any)
- Accepts monitor and/or data (optional) recently read from the the control systems attached.
- Returns set values (optional) to be written to and executed by the control systems attached after the execution of the component's extension code
Data formats (in/out):
- GUI data (out: String):
- Live: <value>data[startIndex],..,data[stopIndex]</value><timeStamp>timeStamp<?timeStamp>
- History: <value>data1</value&><timeStamp>timeStamp1</timeStamp><value>data2</value><timeStamp>timeStamp2</timeStamp>.....
- GUI data (out: ByteArrayOutputStream): jpeg-encoded image
- Monitor data (in: String)
- Live: <value>data[startIndex],..,data[stopIndex]</value><timeStamp>timeStamp</timeStamp>
- History: <value>data1</value><timeStamp>timeStamp1</timeStamp><value>data2</value><timeStamp>timeStamp2</timeStamp>.....
- Receiver data (in: ByteArrayOutputStream): jpeg-encoded image
- Remote command data (out: String): remoteCommandURI(setValue)
- Action data (out: String): actionURI(setValue)
Parameters:
- web2cComponentType Web2c-type of component associated to this extension
- web2cComponentRemoteCommandURI array of remote command URI
- web2cComponentData array of data (GUI data or remote commands)
- monitorURI array of monitor URI to be read prior to executing the extension code
- monitorData array of monitor data (in same order as monitorURI array)
- receiverURI array of video receiver URI to be read prior to executing the extension code
- receiverData array of video receiver data (in same order as receiverURI array)
- actionURI list of remote actions to be performed after executing the extension code
- actionData list of remote actions including set values (in same order as actionURI array)
Returns:
- execution status
Methodes to be implemented:
- public int executeExtensionCode(String web2cComponentType,
Object[] web2cComponentData,
String[] monitorURI,
String[] monitorData,
String[] receiverURI,
ByteArrayOutputStream[] receiverData,
String[] actionURI,
String[] actionData)
[back]
Archive
Viewer Component Reference
Component
Description
Applicable Attributes
Remarks
form to select data channels and time interval; might be hidden
backgroundColor, border, borderColor, bounds, compositeEntry, defaultCompositeEntry, defaultSingleEntry, id, singleEntry, tooltipText, uri, visible
singleEntry: as many entries as items
compositeEntry: as many entries as items
uri: as many entries as data channel addresses
if hidden, a defaultSingleEntry or a defaultCompositeEntry has to be specified
chart of selected data
backgroundColor, border, borderColor, bounds, id, inline, lineType, plotAxis, plotType, tooltipText, yMax, yMin
embedded Web2c Archive viewer page
bounds, id, uri
bounds: top/left corner position used only
Web2c Archive Viewer page
caption, expert, ipAddress
expert: as many entries as expert names
supervisor: as many entries as supervisor names
ipAddress: as many entries as addresses
page section
backgroundColor, border, borderColor, bounds, id
[back]
Archive
Viewer Attribute Reference
Attribute
Description
Value
Format
background color value of component
black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, yellow
Note: the colors listed in the extended CSS color palette might not be supported by all browsers
text string
border mode
none, thin, thick
text string
border color value of component
black, white, aqua, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, yellow
Note: the colors listed in the extended CSS color palette might not be supported by all browsers
text string
all components (except Section and EmbeddedPage): position and size of the component, measured relatively to the section the component belongs to
Section: position and size, measured relatively to the browser window
EmbeddedPage: position only, measured relatively to the browser window, size is not used
x-position of left upper corner (px), y-position of left upper corner (px), x-position of right lower corner (px), y-position of right lower corner (px)
Note: x-position of right lower corner > x-position of right upper corner, y-position of right lower corner > y-position of right upper corner
four comma separated integer numbers (e.g. 23,17,456,645)
if the selector form is visible, the bounds coordinates have to be specified as following:
- section: 0,0,1260,830
- data selector: 0,0,1260,470
- data plot: 0,470,1260,830
if the selector form is hidden, the bounds coordinates have to be specified as following:
- section: leave blank
- data selector: leave blank
- data plot: 0,0,1260,360
text value (Page title)
any text
text string
specifies a composite data channel item; consists of a set of single data channel items
any list of single entry descriptions
list of single entry descriptions; comma separated
data displayed if selector form is hidden
any composite entry description
text string
data displayed if selector form is hidden
any single entry description
text string
expert name
any text
text string
page-wide unique component identifier
Note: embedded pages may contain the same component identifiers
any text
text string
option to align the archive plots of (multiple) embedded pages:
- all archive plots have the same left x-offset (left)
- chart and axis areas of all archive plots have fixed sizes
- all zoom - buttons are invisible
- reset - / backward - and forward -button are placed to the right of the archive plots
- all archive plots are synchronized and display always the same time interval
yes: option enabled
no: option disabled
text string
IP address; requests to set a value are accepted from the address specified only
any text
text string
(e.g. 131.169.150.83, 131.169.150.*, 131.169.*.*, 131.*.*.*; *.*.*.*)
rendering type of data points
Note: plotType setting "lin" or "log" only
dot: dots
line: line
linedot: line and dots
text string
single- or multi- axis plot
single: common axis for all data traces
multi: individual axis for each data trace as specified by corresponding singleEntry definition
text string
plot mode
Note: single-axis mode only
lin (linear vertical axis), log (logarithmic vertical axis),
step and logstep (step-like data changes, such as 0 ® 1 ® 0 etc.)
state (Gantt-chart like data, such as on, off, undefined, etc.)
bit (Gantt-chart like data, extracts specific bit from a field of bits)
text string
specifies a single data channel item
description: any text
control system address index: any integer number
plot type specification:
- lin (linear vertical axis), log (logarithmic vertical axis),
- step and logstep (step-like data changes, such as 0 ® 1 ® 0 etc.)
- state (Gantt-chart like data, such as on, off, undefined, etc.)
- bit (Gantt-chart like data, extracts specific bit from a field of bits)
vertical data minimum value, vertical data maximum value: any number
text string:
description_text,control_system_address_string_index, plot_type_specification,vertical_data_minimum_value, vertical_data_maximum_value
e.g.
- DESY Beam Current [mA],1,lin,0,2.5
- ACC2 ,22,bit(12),0,0
- DORIS Hor.Position Control,4,state,0,0
- Vacuum Pressure in Gun Section [mbar],1,logstep,1.0E-11,1.0E-7
component tooltip text
any text
text string
file name (EmbeddedPage), control system address string (ArchiveViewerDataSelector)
any valid file name or control system address string (preceded by an unique index number)
file name:
file://file_name.mime_type (e.g. file://embedded.xml)
control system address:
index,control_system_name://control_system_address (e.g. 1,tine:///TEST/LxSineGen/SineGen2/Sine()
indicates whether the selector form is visible or hidden; used in case of (multiple) embedded pages
visible, hidden
text string
maximum value of y-axis displayed, ignored if yMin = yMax
Note: single-axis mode only
any value
text string (e.g. 0.0)
minimum value of y-axis displayed, ignored if yMin = yMax
Note: single-axis mode only
any value
text string (e.g. 35.8)
[back]
The Messenger Configuration File ("WebContent/userdocs/messenger.xml") customizes the Web2cMessenger service:
<messenger>
<expert>xyz</expert>
<expert>...</expert>
<supervisor>xyz1</supervisor>
<supervisor>...</supervisor>
<exclusive>xyz</exclusive>
<exclusive>...</exclusive>
<ipAddress>x.x.x.x</ipAddress>
<ipAddress>...</ipAddress>
<uri>uri</uri>
<uri>...</uri>
<service>
<Twitter>
<caption>xyz</caption>
<line>xyz, nn0.00, uri</line>
<line>...</line>
</Twitter>
<Twitter>...</Twitter>
</service>
</messenger>
Field description:
- expert: expert name
- supervisor: supervisor name
- exclusive: exclusive user name, read access is granted to the exclusive users only and not to any user
- ipAddress: expert address, requests to set a value are accepted from the address specified only
- uri: control system address string provided for early monitor link registering at servlet startup
- service: messaging service
- Twitter: message definition
- caption: message title
- line: message content (description, data format, control system address)
[back]
Gateway HTTP-Post API Reference
Method Description
Input Parameter (param=...)
Remarks
Checks the alive-status of the servlet.
checkAlive
Returns "alive" if the servlet is running.
Opens a Web2c session (read-only). Does not require a login procedure.
loginGuest
Returns a list of session-dependent templates to perform register, update, execute and logout requests.
Requests a MD5 encryption key to encrypt the password for a secure user authentication and authorization expert login procedure. The expert names have to be specified in the Web2cGateway.xml file hosted by the web server.
loginExpert
Returns a MD5 encryption key to be used to encrypt the password and a session-dependent template to perform a login procedure.
Opens a Web2c session (read and write) with secure user authentication and authorization expert login procedure.
<elogin>
<sessionId>sessionId</sessionId>
<username>"username"</username>
<password>"encryptedPassword"</password>
<timeStamp>"timeStamp"</timeStamp>
</elogin>
The sessionId is provided by the server in response to an expert login request.
The user name ("username"), the encrypted password ("encrypted password") and the present time ("timeStampInMillis") has to be provided by the client.
Returns a list of session-dependent templates to perform register, update, execute and logout requests.
Closes a Web2c session.
<action>
<sessionId>sessionId</sessionId>
<value>logout</value>
<timeStamp>"timeStampInMillis"</timeStamp>
</action>
The sessionId is provided by the server in response to successful guest- or expert-login procedure.
The present time ("timeStampInMillis") has to be provided by the client.
Establishes a single monitor or a list of control system monitors (i.e. periodically updated control system connections)
<action>
<sessionId>sessionId</sessionId>
<value>
<do>register</do>
<parameter>
.....
</parameter>
</value>
<timeStamp>"timeStampInMillis"</timeStamp>
</action>
The sessionId is provided by the server in response to successful guest- or expert-login.
A single or a list of control system addresses ("uri") and the present time ("timeStampInMillis") have to be provided by the client.
Action may be repeated until registering has been successfully performed at the server. Returns a notification while registering.
Updates the read-back value(s) of a single or a list of control system monitors .
<action>
<sessionId>sessionId</sessionId>
<value>
<do>update</do>
<parameter>
.....
</parameter>
</value>
<timeStamp>"timeStampInMillis"</timeStamp>
</action>
The sessionId is provided by the server in response to successful guest- or expert-login.
A single or a list of control system addresses ("uri") and the present time ("timeStampInMillis") has to be provided by the client.
Returns the requested read-back values.
Sends a single write-request or a list of write-requests to the control system
<action>
<sessionId>sessionId</sessionId>
<value>
<do>execute</do>
<parameter>
.....
</parameter>
</value>
<timeStamp>"timeStampInMillis"</timeStamp>
</action>
The sessionId is provided by the server in response to successful guest- or expert-login.
A single or a list of control system addresses ("uri") and the present time ("timeStampInMillis") has to be provided by the client.
[back]
Gateway Configuration File Specification
The Gateway Configuration File ("WebContent/userdocs/gateway.xml") customizes the Web2cGateway servlet:
<gateway>
<expert>xyz[x.x.x.x]</expert>
<expert>...</expert>
<supervisor>xyz[x.x.x.x]</supervisor>
<supervisor>...</supervisor>
<exclusive>xyz[x.x.x.x]</exclusive>
<exclusive>...</exclusive>
<ipAddress>x.x.x.x</ipAddress>
<ipAddress>...</ipAddress>
<uri>uri</uri>
<uri>...</uri>
</gateway>
Field description:
- expert: expert name, optional: IP address; expert privilege granted only in case address is matching
- supervisor: supervisor name, optional: IP address; supervisor privilege granted only in case address is matching
- exclusive: exclusive user name, read access is granted to the exclusive users only and not to any user
- ipAddress: expert address, requests to set a value are accepted from the address specified only
- uri: control system address string provided for early monitor link registering at servlet startup
[back]
Web2cLogbook Configuration File Specification
The Logbook Configuration File ("WebContent/userdocs/myLogbook.xml") customizes the Web2cLogbook "myLogbook".
<logbook>
<periode>xyz</periode>
<expert>
<name>xyz</name>
<name>...</name>
</expert>
<supervisor>
<name>xyz</name>
<name>...</name>
</supervisor>
<ipAddress>
<address>x.x.x.x</address>
<address>...</address>
</ipAddress>
<exclusive>
<name>xyz</name>
<name>...</name>
</exclusive>
<category>
<keyword>xyz</keyword>
<keyword>...</keyword>
</category>
<importance>
<level>xyz</level>
<level>...</level>
</importance>
<recipient>
<name>xyz@a.b.c</name>
<name>...</name>
</recipient>
<report>
<record>
<caption>xyz</caption>
<category>xyz</category>
<importance>xyz</importance>
<mode>xyz</mode>
<condition>uri=abc</condition>
<recipient>
<name>xyz</name>
<name>...</name>
</recipient>
<text>
<line>xyz, nn0.00, uri</line>
<line>...</line>
</text>
</record>
<record>...</record>
</report>
</logbook>
Field description:
- caption: logbook title
- periode: logbook time structure (i.e. "shift", "day", "week", "month", "year")
- expert:
- name: expert name
- supervisor:
- name: supervisor name
- exclusive:
- name: exclusive user name, read access is granted to the exclusive users only and not to any user
- ipAddress:
- address: expert address, requests to set a value are accepted from the address specified only
- category:
- keyword: keyword (e.g. "software", "hardware")
- importance:
- level: level (e.g. "error", "info")
- recipient:
- name: e-mail recipient's name
- report:
- record:
- caption: title
- category: category keyword
- importance: importance level
- mode: auto-reporting mode (i.e. "manual", "auto")
- condition: condition to be fulfilled to generate auto-report (if mode = auto)
- recipient: report recipient's address
- text:
- line: content (description, data format, control system address)
[back]
Build, Deployment and Launching
Besides the standard Java Run-Time Environment (JRE6), building the Web2cToolkit project requires the open and free libraries (higher versions might also work):
jdom.jar (version 1.1)
tine.jar (latest version)
acopbeans.jar (latest version)
jdoocs.jar (latest version)
tango2doocs.jar (latest version)
Google Web Toolkit Software Development Kit (latest version) including:
- gwt-user.jar
- gwt-dev.jar
- validation-api-1.0.0.GA-sources.jar
- validation-api-1.0.0.GA.jar
Note: All .jar-files listed above are included in the most recent version of the "web2cToolkit.war" Web archive file.
The Web2cToolkit project includes
a free Java MD5 hash generator written by Karsten Bettray and
a free Javascript MD5 hash generator written by Paul Johnston
The Web2cToolkit is tested with Apache Tomcat 7.0 (and previous versions) running Java Virtual Machine JVM 1.6.0_xx on Linux or Windows. The JVM version which the web server is configured for must coincide with the system's JVM version.
To deploy the Web2cToolkit project,
stop the web server,
if existing, delete the Web archive file "web2cToolkit.war" and the directory ".../...tomcat.../webapps/web2cToolkit" on the web server,
copy the new Web archive file "web2cToolkit.war" to the directory ".../...tomcat.../webapps" of the web server, and
start the web server. The server automatically creates the context directory "web2cToolkit". The sub-directory "web2cToolkit/WebContent/userdocs" contains all user-defined configuration files including "web2cMessengerProfile.xml"
The registry file ("web2cUsers.xml") containing the authentication data of the registered users has to be located in the directory ".../...tomcat.../...../endorsed" of the web server. A sample file ("web2cUsers.xml") can be found in the directory "web2cToolkit/web2cdocs".
An instance of the registry file must exist before the Web2cToolkit is launched. During run-time, it can be edited and saved through the Web2cManager.
The initialization file ("web2cToolkitInit.xml") containing the initialization parameter for Web2cToolkit has to be located in the directory ".../...tomcat.../...../endorsed" of the web server. A sample file ("web2cToolkitInit.xml") can be found in the directory "web2cToolkit/web2cdocs".
The initialization file ("web2cInit.xml") containing the initialization parameter for both the synoptical display viewer servlet has to be located in the directory ".../...tomcat.../...../endorsed" of the web server. A sample file ("web2cInit.xml") can be found in the directory "web2cToolkit/web2cdocs".
The profile file ("web2cTwitterInit.xml") containing the account authentication data for the Twitter service has to to be located in the the directory ".../...tomcat.../....../endorsed" of the web server. A sample file ("web2cTwitter.xml") can be found in the directory "web2cToolkit/web2cdocs".
The profile file ("web2cSMTPnit.xml") containing the account authentication data for the Twitter service has to to be located in the the directory ".../...tomcat.../....../endorsed" of the web server. A sample file ("web2cSMTP.xml") can be found in the directory "web2cToolkit/web2cdocs".
All initialization files can be created, edited and saved through the Web2cManager.
By default, the Web2cToolkit writes logging information about each user session since the restart of the corresponding servlet into the following files on the directory "web2cToolkit/log":
- synopticDisplaySessionLog.log
- editorSessionLog.log
- archiveViewerSessionLog.log
- gatewaySessionLog.log
- logbookSessionLog.log
- managerSessionLog.log
In addtion, the Web2cToolkit writes debugging information into the following files on the directory "web2cToolkit/log":
- synopticDisplayLog.log
- editorLog.log
- archiveViewerLog.log
- messengerLog.log
- gatewayLog.log
- logbookLog.log
- managerLog.log
Write commands to the control system attached are logged into the following files on the directory "web2cToolkit/log":
- synopticDisplayCdaActionLog.log
- messengerCdaActionLog.log
- gatewayCdaActionLog.log
- logbookCdaActionLog.log
The Web2cToolkit offers 3 different debugging options:
- web communication
- control system communication
- configuration file parsing
By default, all debug logging options are disabled. They can be individually enabled / disabled by entering the keyword "debugWebCommunicationOn" / "debugWebCommunicationOff", "debugControlSystemCommunicationOn" / "debugControlSystemCommunicationOff" and "debugConfigurationFileParsingOn" / "debugConfigurationFileParsingOff" on the user console, respectively. Each input must be terminated by pressing the "Enter" key.
All servlets provide a status page which is accessible through the Web2cManager.
Control System Device and Archive Access
The Web2cToolkit offers generic access to control system devices and control system archives. The following device and archive access plugs are implemented:
Native interface:
In both cases, the Web2c control system plugs must be able to browse the corresponding equipment name services.
Client-side gateway interfaces via the DOOCS plug:
In both cases, device servers are addressed by their corresponding ip_addresses and must not be known to the DOOCS equipment name service.
The Web2cToolkit is capable to receive and redirect JPEG video frames. Receivers for the following transmission protocols are implemented:
RTP: For image capturing and transmitting, the JMStudio application of the Java Media Framework can be used. Run the JMRegistry application once after installing a new camera type on your computer. For transmitting, configure the JMStudio application properly by selecting the correct video source, disabling audio capturing, selecting JPEG/RTP encoding and specifying a valid RTP destination address. A RTP address consist of an ip and a port number. It is recommended but not mandatory to use as ip number a valid multicast address which is routed in the network (Note: At DESY use 238.1.1.1). Alternatively, use a peer-to-peer connection between transmitter and receiver (Note: At DESY use 238.1.Third_Byte_of_Transmitter_IP_Number.Fourth_Byte_of_Transmitter_IP_Number). The port number of the transmitter and the receiver must coincide and not interfere with other services on the network. In addition, the so-called time-to-live (TTL) parameter can be specified. It defines the maximum number of routing steps between transmitter and receiver.
TINE: The TINE control systems offers integrated video transmission capability. For transmitting, specify the TINE address ( /context/server/device/property) pointing to the requested video transmitter source.
TINE
DOOCS
TANGO
EPICS
monitoring parameters
implemented
implemented
implemented
implemented
setting parameters
implemented
implemented
implemented
implemented
receiving video streams
implemented
not implemented
not implemented
not implemented
reading data from archive
implemented
implemented
not implemented
not implemented
[back]
All client-side tools work properly with the following browser implementations:
Microsoft Internet Explorer ver. 7.0.x.x, 8.0.x.x and 9-beta (Windows)
Note: In rare cases IE7 might exhibit incompatibilities or generate errors. The following problems have been identified:
Web2cComponent id: IE7 is case-insensitive. It does not distinguish between "id" and "Id".
URL length: The maximum URL length handled by IE7 is limited to 2083 characters. This might affect complex archive plots.
Mozilla Firefox ver. 3.6.x (Windows)
Iceweasel (Mozilla Firefox) ver. 3.0.x (Linux)
Konqueror ver. 3.5.x (Linux)
Epiphany ver. 2.22.x (Linux)
Safari ver. 4.0.x (Windows, MAC OS X, MAC OS X iPhone)
Opera ver. 10.x (Windows, Windows Mobile)
Google Chrome 6.0.x.x (Windows, Android)
Other browser implementations might also work but have not been tested.
To download a client-side Web2cToolkit page, enter the following URL in the browser's address field:
- Synoptic display viewer:
- http://hostname[:port]/web2cToolkit/Web2c?param=(file)foldername/.../pagename.xml[,languageCode] orhttp://hostname:[port]/web2cToolkit/Web2c?param=(open)foldername/.../pagename.xml[,languageCode]
- the optional parameter "languageCode" is a number (default: 0) indicating the corresponding index in the caption, headerCaption, tooltipText, legend or message description lists.
- Archive viewer:
- http://hostname[:port]/web2cToolkit/Web2cArchiveViewer?param=(file)foldername/.../pagename.xml[,fromTimeStamp, toTimeStamp] or http://hostname:[port]/web2cToolkit/Web2cArchiveViewer?param=(open)foldername/.../pagename.xml[,fromTimeStamp, toTimeStamp]
- format of optional parameters: yyyy-mm-dd hh:min:ss
- Synoptic display editor:
- http://hostname[:port]/web2cToolkit/Web2cEditor?param=(file)Web2cEditor.xml
- E-Mail / SMS form:
- http://hostname[:port]/web2cToolkit/Web2cMessenger?param=(file)SendMessagePage
- Logbook viewer:
- http://hostname[:port]/web2cToolkit/Web2cLogbook?param=(file)foldername/.../logbookname.xml
- Manager Page:
- http://hostname[:port]/web2cToolkit/Web2cManager?param=(file)ManagerPage
Note: The parameter "(file)" opens a login dialogue prior to page download, "(open)" grants unprivileged access without user authentication.
To download a page with status information about a servlet, enter the following URL in the browser's address field:
- for all servlets: http://server_name:port/web2cToolkit/servlet_name?param=(file)DiagnosticsPage
Login procedure:
