Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
National Superconducting Cyclotron Laboratory API MANUAL Project Name Project Code Account Department Project Leader Project Coordinator Serialization of EPICS Datatype Standards SEDS Controls and Computing Sheng Peng Vasu Vuppala Name Prepared By Reviewed By Approved By Aaron Barber Signature Date 7/14/14 Serialization of EPICS Datatype Standards Revision History Version 1.0 Date 7/14/14 [BASELINE 14-JUL -14] Author Aaron Barber Description Initial document Page 2 of 12 Serialization of EPICS Datatype Standards Table of Contents 1 INTRODUCTION ............................................................................................................................................. 5 1.1 1.2 1.3 1.4 1.5 PURPOSE .........................................................................................................................................................5 SCOPE.............................................................................................................................................................5 DEFINITION, ACRONYMS, AND ABBREVIATIONS .......................................................................................................5 REFERENCES .....................................................................................................................................................6 OVERVIEW .......................................................................................................................................................6 2 INSTALLATION ............................................................................................................................................... 6 3 JAVA INTERFACE ............................................................................................................................................ 7 3.1 PRODUCT FUNCTIONS ........................................................................................................................................7 3.1.1 Creating SEDS Data in Memory................................................................................................................8 3.1.2 JSON Conversion ......................................................................................................................................9 3.1.3 EPICS VType Conversion .........................................................................................................................10 3.1.4 CSV Conversion ......................................................................................................................................11 4 EXCEPTION HANDLING ................................................................................................................................ 12 5 SUPPORT ..................................................................................................................................................... 12 [BASELINE 14-JUL -14] Page 3 of 12 Serialization of EPICS Datatype Standards List of Figures and Tables Table 1 Glossary ............................................................................................................................................ 5 [BASELINE 14-JUL -14] Page 4 of 12 Serialization of EPICS Datatype Standards 1 Introduction National Superconducting Cyclotron Laboratory (NSCL) is a world leader in rare isotope research and nuclear science education. NSCL scientists and researchers conduct advanced research in fundamental nuclear science, nuclear astrophysics, and accelerator physics. To facilitate the research, NSCL operates multiple particle accelerators. The control system at NSCL enables operators to control the various devices in the lab: ion sources, cyclotrons, beam lines, experimental devices, and auxiliary equipment. It is based on the Experimental Physics and Industrial Control Systems (EPICS) standard. EPICS is a distributed soft real-time control system for large scientific experiments. SEDS is a protocol for data processing. SEDS provides a set of software designs for high level composite data types suitable for the application level data exchange between EPICS V4 network endpoints. SEDS provides protocol documentation and datatype schemas. The intent is to serialize and deserialize the datatypes as self-describing data for persistence. SEDS protocol specifies JSON as the self-describing data language used to represent all SEDS data structures. This project will provide users the ability to transmit standardized data between programming languages and to store standardized data in a database. SEDS consists of the following: Protocol documentation o Data structures supported by SEDS o JSON Schemas to validate JSON data to conform to SEDS protocol Java API o Convert SEDS data structures between VType structures, JSON structures, and CSV data 1.1 Purpose The objective of this document is to describe the methods of programmatically working with the SEDS protocol through the SEDS API. 1.2 Scope This document provides an overview of the API. 1.3 Definition, Acronyms, and Abbreviations Table 1 Glossary Item SEDS Controls EPICS NSCL FRIB CSV [BASELINE 14-JUL -14] Description Serialization of EPICS Datatype Standards FRIB’s Controls and Computing Department Experimental Physics and Industrial Control System National Superconducting Cyclotron Laboratory Facility for Rare Isotope Beams Comma Separated Values Page 5 of 12 Serialization of EPICS Datatype Standards JSON PV JavaScript Object Notation Process Variable. Identifier for a data item in EPICS. 1.4 References 1. Open EPICS Web Site, http://openepics.sourceforge.net 1.5 Overview The next section describes the prerequisites for using the API. The subsequent section describes the Java interface. 2 Installation To be able to implement a custom API, you must first install the SEDS protocol documents. If you intend to use the Java API, you must download the corresponding libraries. The SEDS repository contains both these modules. The documentation and the libraries are available in the SEDS repository. The Java API depends on the schema files from the protocol documents. Ensure that the version of the Java API and the version of the schemas match. [BASELINE 14-JUL -14] Page 6 of 12 Serialization of EPICS Datatype Standards 3 Java Interface This section discusses the API summary for the Java implementation of the SEDS protocol. The Java API defines the SEDS data structures as objects, and provides processing objects to work with them. The Java API works with three object types: SedsType objects, VType objects, and JsonObject objects. SedsType objects are the SEDS data structures. VType objects are the EPIC VType data structures that are parallel to SedsType objects. JsonObject objects are the JavaEE representation of a map of namevalue pairs (representation of JSON in memory). The Java API provides a converter object that maps the data between these three object types. The Java API provides processing objects to import and export JsonObject objects to a source (such as a stream, file, or string). The Java API provides processing objects to import and export the major SEDS data structures to and from a CSV file. The Java API provides factory objects to create SEDS data structures directly from raw data (primitive data types in Java). The Java API follows the builder design pattern, and the class “org.openepics.seds.core.Seds” provides access to all processing objects. Processing objects provide conversion, serialization, deserialization, and input/output utilities. The protocol documentation provides extensive detail on the SEDS data structures and discusses the process of how SEDS data is structured in JSON. 3.1 Product Functions The following are the primary functions a user would use the SEDS Java API to accomplish. [BASELINE 14-JUL -14] Page 7 of 12 Serialization of EPICS Datatype Standards 3.1.1 Creating SEDS Data in Memory The following describes several ways to create a SEDS data structure in memory and populate it with data. The Java API uses the builder design pattern, and a factory is provided to handle constructing the objects. //Creating SEDS data in memory SedsType value = Seds.newFactory().newScalar( 1234, Seds.newFactory().newAlarm( AlarmType.MAJOR, "noStatus", "simpleAlarm" ), Seds.newFactory().newControl( 10d, 100d ), null, //Display Data Seds.newFactory().newTime( Timestamp.of(1354719441, 521786982), -1 ) ); //Creating SEDS data in memory SedsType value = Seds.newSimpleFactory().newScalarArray( new Double[]{1.0, 1.1, 2.0, 2.1} ); //Creates a table SedsTable table = Seds.newSimpleFactory().newTable( new String[]{"time","velocity"}, new String[]{"s", "m/s"}, new Object[][]{ new Integer[]{0, 1, 2, 3, 4, 5}, new Double[]{9.0, 13.0, 16.0, 18.0, 19.0, 18.0}, } ); [BASELINE 14-JUL -14] Page 8 of 12 Serialization of EPICS Datatype Standards 3.1.2 JSON Conversion The following demonstrates the process to serialize and deserialize SEDS data structures. Serialization refers to mapping the data of a SEDS data structure to a JsonObject. Deserialization refers to mapping the data of a JsonObject to a SEDS data structure. A reader and a writer processing object are provided to convert the JsonObject to/from a data source (such as a file or string). //Serializing SEDS data in memory into a JSON file SedsType value = ...; Writer src = ...; JsonObject jValue = Seds.newSerializer().serializeSEDS(value); Seds.newWriter().write(jValue, src); //Deserializing a JSON file into SEDS data in memory Reader src = ...; JsonObject jValue = Seds.newReader().read(src); SedsType value = Seds.newDeserializer().deserializeSEDS(jValue); [BASELINE 14-JUL -14] Page 9 of 12 Serialization of EPICS Datatype Standards 3.1.3 EPICS VType Conversion The following demonstrates the process to convert (or map the data from type X to type Y) between the type systems (VType objects, SedsType objects, and JsonObject objects). Note that the converter object provides functions to map to any of the three type systems from any of the other type systems. In this context, the VType system is referred to as the “client” type. Additionally, because the VType tag interface does not overlap all types represented in SEDS (there exists a SedsAlarm which extends SedsType, but Alarm (the VType) does not extend VType), casting must be done on the return of the “toClientType” method call. //Working with VTypes SedsConverter<VTypeMapper> mapper = Seds.newVTypeConverter(); //Initial data SedsType sedsValue = ...; JsonObject jsonValue = ...; VType vtypeValue = ...; //Convert to SEDS SedsType a = mapper.toSEDS(jsonValue); SedsType b = mapper.toSEDS(vtypeValue); //Convert to JSON JsonObject c = mapper.toJSON(sedsValue); JsonObject d = mapper.toJSON(vtypeValue); //Convert to VTYPE VType e = (VType) mapper.toClientType(sedsValue); VType f = (VType) mapper.toClientType(jsonValue); //Example //This function takes the VType “double” value, //converts the value to a JsonObject, //and serializes the JsonObject as a String public String getJSON(VDouble value) throws SedsException{ SedsConverter<VTypeMapper> mapper = Seds.newVTypeConverter(); SedsWriter writer = Seds.newWriter(); return writer.write(mapper.toJSON(value)); } [BASELINE 14-JUL -14] Page 10 of 12 Serialization of EPICS Datatype Standards 3.1.4 CSV Conversion The following demonstrates the process to import/export between the SedsTable data structure and CSV files. //Reading a SEDS Table from CSV BufferedReader reader = ...; SedsTable data = Seds.newCSVConverter().importTable(reader); //Writing a SEDS Table to CSV BufferedWriter writer = ...; SedsTable output = ...; Seds.newCSVConverter().exportTable(output, writer); //File Format //File Extension: .csv //File Contents: (see below) //Row 1: list of column names //Row 2: list of column units //Row 3 ... N: column values name1,name2,...,nameN unit1,unit2,...,unitN value11,value12,...,value1N value21,value22,...,value2N ... valueN1,valueN2,...,valueNN //Example //File Name: example.csv //File Contents: (see below) Distance,Shape,Time Meters,,Seconds 10.1,flat,5 30.3,round,5 20.2,flat,10 90.9,round,10 [BASELINE 14-JUL -14] Page 11 of 12 Serialization of EPICS Datatype Standards 4 Exception Handling In the current version: Java API o Errors propagate and attach JSON data that caused the error o SedsException errors are propagated when JSON data is not valid according to the JSON schema from the SEDS protocol o IllegalArgumentException errors are propagated from illegal values such as null arguments o Data is NOT validated when creating SEDS data structures in memory o Data is validated when serializing and deserializing 5 Support To report errors, corrections, and suggestions please visit the SEDS web site [1]. [BASELINE 14-JUL -14] Page 12 of 12