search

vatplanner / dataformats-vatsim-public

library for parsing and processing publicly accessible VATSIM data formats
MIT License
1 stars 0 forks source link

readme

Data Format Parsers & Entities for Publicly Available VATSIM Information

Coverage Status Maven Central JavaDoc License: MIT

This library's goal is to provide parsers and entities for data formats used by VATSIM and provided publicly. It's not possible to connect to the actual network using this library as VATSIM uses an undisclosed (NDA'd) network protocol and the network is only permitted to be connected to with authorized software. Actually, this library doesn't connect at all, it just parses and will require you to fetch all source data and feed it into the parser yourself... :)

The scope of this project is rather small but an essential part of a bigger project I'm working on (VATPlanner). Ut still seemed like a good idea to split the data parsers & entities apart to be easily reusable if needed in other projects.

Features

Implemented:

Planned:

Build instructions

Due to recent ongoing refactoring you will need to locally install the latest development version (0.1-SNAPSHOT) of VATPlanner Commons until it gets published to Maven Central.

Current API State

API is currently not stable and may change without notice. Restructuring of the whole project is currently pending (#18). A stable release should be expected after restructuring is complete; 0.1-pre-releases are published prior to that.

Privacy filter was under construction and is now deprecated as it requires a major rework due to JSON format introduction. It should not be used in current state.

Examples and Development Tools

See dataformats-vatsim-public-examples for a collection of development tools which may also be useful to look into as "example code" on how to use this library.

License

The implementation and accompanying files are released under MIT license. Parsed data is subject to policies and restrictions, see the disclaimer below.

Disclaimer and Policies

This section is a copy of DISCLAIMER.md.

Use of real-world aviation formats

VATSIM uses some data in the same way as in real-world aviation, for example ICAO flight plan equipment codes (field 10a/10b and PBN remarks), so parsers and data representations for such formats have also been added to this library. Although such data is supported by this library such classes should not be blindly used for real-world aviation. Such "unsafe" classes generally hold an additional disclaimer on class JavaDoc but it could also be missing in some cases. Note that there generally is no warranty given for any code in this library but applying classes/data from a library of an unprofessional simulation environment for real-world aviation use in particular would be highly irresponsible to say the least. Also note that parser/data present in this library may have adjusted to the specific needs of VATSIM, so although they look compatible to real-world scenarios they result in invalid data when applied outside the context of VATSIM/flight simulation. You have been warned...

Privacy filtering

Privacy filter was under construction and is now deprecated as it requires a major rework due to JSON format introduction. It should not be used in current state.

As a fallout from GPDR and local law and regulations, it appeared to make sense to implement a privacy filter to help with removal of some information from data files. However, even in case that it should work properly, it will not magically make your program compliant with any data protection laws. Read the full disclaimer and all JavaDoc documentation before attempting to use it:

THERE IS NO GUARANTEE THAT THE PROVIDED PRIVACY FILTERING MECHANISM WORKS
RELIABLY, NEITHER IN TERMS OF PROTECTING PRIVACY NOR MAINTAINING INTEGRITY OR
AVAILABILITY OF DATA.

IT IS ONLY TO BE UNDERSTOOD AS A SINGLE FIRST TOOL YOU CAN UTILIZE IN YOUR
OWN EFFORTS TO BUILD, OPERATE AND MAINTAIN A CHAIN OF COMPONENTS PROCESSING
AND STORING DATA IN A LEGALLY COMPLIANT, TRUSTWORTHY AND RESPONSIBLE WAY
THROUGHOUT YOUR ENTIRE INDIVIDUALLY CRAFTED SYSTEM. APPLYING THIS FILTER,
EVEN WHEN WORKING AS DESIRED, CAN NOT FREE YOU FROM YOUR OWN
RESPONSIBILITIES.

CONFIGURATION OF THE FILTER AS WELL AS ALL FURTHER HANDLING OF DATA REQUIRES
YOUR OWN JUDGMENT AND PRE-CAUTIONS. BY COMMON SENSE, ALL DATA SHOULD BE
REDUCED FURTHER WHENEVER POSSIBLE, WHICH IS BEYOND THE CAPABILITIES PROVIDED
BY THIS INITIAL FILTER.

PROCESSING ANY INFORMATION REMAINING AFTER APPLYING THE FILTER STILL REQUIRES
INDIVIDUAL ASSESSMENT AND IS YOUR OWN RESPONSIBILITY!

FILTERED DATA OBVIOUSLY REMAINS SUBJECT TO VATSIM POLICIES AND RESTRICTIONS.
EXPLANATIONS OF CONFIGURATION OPTIONS AS WELL AS THIS DISCLAIMER ITSELF ONLY
DESCRIBE THOUGHTS AND OBSERVATIONS BY PROGRAM AUTHORS AND ARE NOT TO BE
CONFUSED WITH LEGAL ADVICE WHICH CANNOT BE PROVIDED.

Usage and retrieval of VATSIM data

Although this implementation is provided under an open license, usage of the data itself, while being publicly available, is subject to restrictions. Please refer to official VATSIM documents regarding any policies associated with its use.

Some technical policies stressed explicitely on the initial status.txt file should be repeated here as otherwise they may go unnoticed when using this library:

Further or updated policies may be in effect; please read all available VATSIM-provided documents and regularly check the raw source files you are feeding into these parsers.

If you are debugging this library or are wondering about some missing/erroneous data you may want to have a look at the (incomplete) list of datafile oddities which have been observed so far while importing larger amounts of live data.