SDK (Java): Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
No edit summary
 
(24 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{technical}}
Te Java SDK is a [[Software Development Kit]] written in and for Java, developed in lockstep with the {{software}} itself. It is used internally for the development of the client application, by communicating via the [[API]].
{{learned|what a Software Development Kit (SDK) is|how the SDK relates to the Tygron Engine|where to find the SDK|how to get started with the SDK}}


==What is a Software Development Kit?==
===Obtain and use===
A software Development Kit (SDK) is a (collection of) software or programming resources, which are designed to make a programming task easier. Often, software or hardware which is designed to accept input from other programs also have an appropriate SDK.
The SDK is freely available via the API of the {{software}}. For the LTS-compatible version, it can be found in the following location:


==How does the SDK relate to the Tygron Engine?==
https://engine.tygron.com/api/developer/.  
The Tygron Engine offers an [[API]], which allows external application to interact with it. However, the specific options available via the API are not always intuitively relatable to specific operations when using the client application. To compensate for this, the SDK wraps a number of these operations into more human-understandable functions. In addition, it provides functionality to handle some of the complexity related to obtaining, storing, updating and using data present in the Tygron Engine.


==Getting started with the SDK==
The contents are an Eclipse Java Project which can be imported as a dependency for other Projects. Instructions for its installation and use are included in a README file.
At this time, the SDK is only available for Java, and is still in development. The recommended IDE is [https://eclipse.org/ Eclipse], although other developments environments can be used as well.


===Obtaining the SDK===
===Components===
The SDK is freely available from [https://github.com/Tygron/SDK github], and can be obtained using either SVN or Git. The following projects are contained in the repository:
The following components are available in the Java SDK:
* '''Core''' (required). This project contains all essentials of the SDK
* ''Examples''. This project contains a number of examples for interacting with the Tygron Engine both with and without the SDK.
* ''Tools''. This project contains practical tools developed using the SDK and made available to the public. These also serve as practical examples.
 
===Setting up the SDK for use===
The Core project can be used as dependency of your application. The other projects have the Core as their dependency. For first time usage, it is recommended to test your setup by running one or more of the examples. To run the examples, you will need to add your Tygron credentials to the setup. For instructions on adding your credentials to the examples, see the [https://github.com/Tygron/SDK/blob/master/java/README.md Readme] of the SDK.
 
==Using the SDK==
''Please note: because the SDK is still in development along with the Tygron API, the following information is subject to rapid change.''


===Components===
{|class="table sortable overlay"
Using the SDK means using one or more of the components provided to interact with the Tygron Engine. The SDK can be used as a library of functionality, just as most other software libraries. The SDK offers a number of features designed to make interaction with the Tygron API easier. The following components are most important, and can contribute the most to your application.
! Component!! Description
|-
| SettingsManager || Stores most recently used settings. Required by other components of the SDK.
|-
| ServicesManager || Facilitates authentication and communication to the {{software}}.
|-
| |Projects and Sessions || The data contained in a Project (such as [[Building]]s and [[Overlay]]s), and the live in-memory state of that Project data respectively.
|-
| SlotConnection || The connector to one specific session, facilitating interactions and a continuously updating representation of data.
|-
| EventManager || Allows for the listening of specific occurrences or events from the Session.  
|-
| MapLinks and Items || The enumerating types of all the available data, as well as the actual data from a Project respectively.
|-
| JTS Topology Suite{{ref|jts}} || An included library for the definition of geo data, as well as the translations of geo data.  
|}


====Data Connector====
==Examples==
The Data Connector and Extended Data Connector  serve as the connection between your application and the API. Calls to fire specific events or requests for specific data can be placed with the DataConnector, and will return a Data Package, with the (raw) returned data. The Extended Data Connector offers additional functionality for starting and stopping sessions with a single function call.
The SDK contains example code which can be run both to test the functionality and successful installation of the SDK, but also to provide a first script which can be copied, changed, and expanded upon to create further tools.  
====Data Module and Player Module====
The Data Module and Player Module are meant to be used together with the Data Connectors, connected to an actual session. They wrap basic events and data requests in functions, and return only the relevant return value of the call. The Data Module can be used for generic retrieval of data. The Player Module contains functions which mimic player actions.
====Data Monitor and Update Monitor====
The Data Monitor and Update Monitor allow for retrieving data automatically, rather than on demand. The Update Monitor manages the connection to the "update/" url of a session. When it receives an update, it is stored in a Data Monitor, which records both the most recent states of data in a session, and the "version" of that data. The Update Monitor uses this version to listen only to the most recent changes. With each update received, the Update Monitor also alerts registered listeners, allowing your application to respond immediately.
====Items====
The Items are the representation of the various types of data in a session (such as [[Constructions|Buildings]], [[Stakeholders]], or [[Functions]]. These objects also allow the data pertaining to these items to be stored, but in many cases also offer easier methods of interacting with the data. An example of this is the ability to retrieve the exact function values for the categories of a given function.
====MapLinks and Events====
The Data Connector can be instructed to make a request to any url within the API, by providing a string with the desired url. However, to assure that requested urls are valid, it is recommended to make requests by supplying the MapLink or Event objects.
====Utilities====
In addition to the essential components listed above, a number of utility classes exist as well.
=====Settings=====
The Settings utilities allow for easy loading and storage of credentials and application settings.
=====Json=====
The Json utilities allow for easy deserialization of data sent back by the Tygron Engine. It can deserialize into generic List and Map structures for generic access, or to (Lists or Maps of) specific objects or Items.
=====Data=====
The Data utilities allow for the deserialized data to be cleaned up easily, to make it easier to itterate through programmatically.
=====GamePlay=====
The GamePlay utilities wraps operations together to allow more complex gameplay tasks to be performed, such as finding a building with specific properties or finding a popup related to a building.
===Examples===
For specific examples on how to perform basic tasks using the SDK, please refer to the Examples project in the SDK. This project contains a number of examples for interacting with the API both with and without the SDK.


==Adapting and contributing to the SDK==
Run "ExampleTest" via JUnit to get started.
The SDK is currently still in development, as is the API, which means both the Software Development Kit and the API it communicates with can change rapidly. We aim to keep the two compatible as much as possible. However, it is possible that changes temporarily break functionality of the SDK. If this occurs, you can contact {{support|Tygron Support}}.


Alternatively, because we offer the source code of the SDK freely, it is also possible to make your own changes or improvements to the SDK. If you are interested in contributing to the SDK, please contact {{support|Tygron Support}}.
{{article end
|seealso=
* [[API]]
* [[SDK (Python)]]
|references=
  <references>
    {{ref|jts
      |name=JTS Topology Suite
      |author=
      |page=
      |source=
      |link=https://www.tsusiatsoftware.net/jts/main.html
      |lastvisit=09-07-2024
    }}
  </references>
}}

Latest revision as of 07:49, 9 July 2024

Te Java SDK is a Software Development Kit written in and for Java, developed in lockstep with the Tygron Platform itself. It is used internally for the development of the client application, by communicating via the API.

Obtain and use

The SDK is freely available via the API of the Tygron Platform. For the LTS-compatible version, it can be found in the following location:

https://engine.tygron.com/api/developer/.

The contents are an Eclipse Java Project which can be imported as a dependency for other Projects. Instructions for its installation and use are included in a README file.

Components

The following components are available in the Java SDK:

Component Description
SettingsManager Stores most recently used settings. Required by other components of the SDK.
ServicesManager Facilitates authentication and communication to the Tygron Platform.
Projects and Sessions The data contained in a Project (such as Buildings and Overlays), and the live in-memory state of that Project data respectively.
SlotConnection The connector to one specific session, facilitating interactions and a continuously updating representation of data.
EventManager Allows for the listening of specific occurrences or events from the Session.
MapLinks and Items The enumerating types of all the available data, as well as the actual data from a Project respectively.
JTS Topology Suite[1] An included library for the definition of geo data, as well as the translations of geo data.

Examples

The SDK contains example code which can be run both to test the functionality and successful installation of the SDK, but also to provide a first script which can be copied, changed, and expanded upon to create further tools.

Run "ExampleTest" via JUnit to get started.

See also

References

  1. ↑ JTS Topology Suite ∙ Found at: https://www.tsusiatsoftware.net/jts/main.html ∙ (last visited: 09-07-2024)
Retrieved from "https://support.tygron.com/w/index.php?title=SDK_(Java)&oldid=60530"