mirror of
https://github.com/xpipe-io/xpipe.git
synced 2024-06-28 11:00:28 +12:00
Update readmes
This commit is contained in:
Christopher Schnick
parent
2dabc02a3c
commit
7c88e8cd2d
27
README.md
27
README.md
|
|
@ -3,28 +3,28 @@
|
|||
|
||||
## X-Pipe Java
|
||||
|
||||
The fundamental components of the [X-Pipe project](https://docs.xpipe.io).
|
||||
The fundamental components of the [X-Pipe project](https://xpipe.io).
|
||||
This repository contains the following four modules:
|
||||
|
||||
- Core - Shared core classes of the Java API, extensions, and the X-Pipe daemon implementation
|
||||
- API - The API that can be used to interact with X-Pipe from any JVM-based languages
|
||||
- Core - Shared core classes of the X-Pipe Java API, X-Pipe extensions, and the X-Pipe daemon implementation
|
||||
- API - The API that can be used to interact with X-Pipe from any JVM-based language10
|
||||
- Beacon - The X-Pipe beacon component is responsible for handling all communications between the X-Pipe daemon
|
||||
and the client applications, for example the various programming language APIs and the CLI
|
||||
- Extension - An API to create all different kinds of extensions for the X-Pipe platform
|
||||
|
||||
## Installation / Usage
|
||||
|
||||
The *core* and *extension* libraries are used in X-Pipe extension development.
|
||||
For setup instructions, see the [X-Pipe extension development](https://xpipe-io.readthedocs.io/en/latest/dev/extensions.html) section.
|
||||
The *core* and *extension* modules are used in X-Pipe extension development.
|
||||
For setup instructions, see the [X-Pipe extension development](https://xpipe-io.readthedocs.io/en/latest/dev/extensions/index.html) section.
|
||||
|
||||
The *beacon* library handles all communication and serves as a
|
||||
reference when implementing an API or program that communicates with the X-Pipe daemon.
|
||||
The *beacon* module handles all communication and serves as a
|
||||
reference when implementing the communication of an API or program that interacts with the X-Pipe daemon.
|
||||
|
||||
The *api* library serves as a reference implementation for other potential X-Pipe APIs
|
||||
and is also used to enable your Java program to communicate with X-Pipe.
|
||||
For setup instructions, see the [X-Pipe Java API Usage]() section.
|
||||
The *api* module serves as a reference implementation for other potential X-Pipe APIs
|
||||
and can also be used to access X-Pipe functionalities from your Java programs.
|
||||
For setup instructions, see the [X-Pipe Java API Usage](https://xpipe-io.readthedocs.io/en/latest/dev/api/java/index.html) section.
|
||||
|
||||
## Development
|
||||
## Development Notes
|
||||
|
||||
All X-Pipe components target [JDK 17](https://openjdk.java.net/projects/jdk/17/) and make full use of the Java Module System (JPMS).
|
||||
All components are modularized, including all their dependencies.
|
||||
|
|
@ -33,6 +33,5 @@ These dependency generation rules are accumulated in the [X-Pipe dependencies](h
|
|||
repository, which is shared between all components and integrated as a git submodule.
|
||||
|
||||
Some unit tests depend on a connection to an X-Pipe daemon to properly function.
|
||||
To launch the installed daemon, it is required that the `XPIPE_HOME` environment variable
|
||||
is set or the `xpipe` / `xpipe.exe` CLI executable is added to the `PATH` variable.
|
||||
|
||||
To launch the installed daemon, it is required that you either have X-Pipe
|
||||
installed or have set the `XPIPE_HOME` environment variable in case you are using a portable version.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[](https://maven-badges.herokuapp.com/maven-central/io.xpipe/api)
|
||||
[](https://javadoc.io/doc/io.xpipe/api)
|
||||
[](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-api)
|
||||
[](https://javadoc.io/doc/io.xpipe/xpipe-api)
|
||||
|
||||
## X-Pipe Java API
|
||||
|
||||
|
|
@ -7,11 +7,14 @@ The X-Pipe API for Java allows you to use most of the X-Pipe functionality from
|
|||
|
||||
- Create data stores and data sources
|
||||
- Query and work with the contents of data sources
|
||||
- Write and append to data sources
|
||||
- Write data to data sources
|
||||
|
||||
## Setup
|
||||
|
||||
Either install the [dependency](https://maven-badges.herokuapp.com/maven-central/io.xpipe/api) from Maven Central
|
||||
using your favourite build tool or alternatively download the `api.jar`, `core.jar`, and `beacon.jar`
|
||||
Either install the [maven dependency](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-api) from Maven Central
|
||||
using your favourite build tool or alternatively download the `xpipe-api.jar`, `xpipe-core.jar`, and `xpipe-beacon.jar`
|
||||
from the [releases page](https://github.com/xpipe-io/xpipe_java/releases/latest) and add them to the classpath.
|
||||
|
||||
## Usage
|
||||
|
||||
See [the API documentation](https://xpipe-io.readthedocs.io/en/latest/dev/api/java/index.html).
|
||||
|
|
@ -1,40 +1,64 @@
|
|||
[](https://maven-badges.herokuapp.com/maven-central/io.xpipe/beacon)
|
||||
[](https://javadoc.io/doc/io.xpipe/beacon)
|
||||
[](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-beacon)
|
||||
[](https://javadoc.io/doc/io.xpipe/xpipe-beacon)
|
||||
|
||||
## X-Pipe Beacon
|
||||
|
||||
The X-Pipe beacon component is responsible for handling all communications between the X-Pipe daemon
|
||||
and the various programming language APIs and the CLI. It provides an API that supports all kinds
|
||||
of different operations.
|
||||
The underlying inter-process communication is realized through TCP sockets on default port `21721`.
|
||||
|
||||
The data structures and exchange protocols are specified in the `io.xpipe.beacon.exchange` package.
|
||||
Every exchange is initiated from the outside by sending a request message to the X-Pipe daemon.
|
||||
The daemon then always sends a response message.
|
||||
### Inner Workings
|
||||
|
||||
The header information of a message is formatted in the json format.
|
||||
As a result, all data structures exchanged must be serializable/deserializable with jackson.
|
||||
- The underlying inter-process communication is realized through
|
||||
TCP sockets on port `21721` on Windows and `21722` on Linux.
|
||||
|
||||
Both the requests and responses can optionally include content in a body.
|
||||
A body is initiated with two new lines (`\n`).
|
||||
The body is split into segments of max length `65536`.
|
||||
Each segment is preceded by four bytes that specify the length of the next segment.
|
||||
In case the next segment has a length of less than `65536` bytes, we know that the end of the body has been reached.
|
||||
This way the socket communication can handle payloads of unknown length.
|
||||
- The data structures and exchange protocols are specified in the
|
||||
[io.xpipe.beacon.exchange package](src/main/java/io/xpipe/beacon/exchange).
|
||||
|
||||
- Every exchange is initiated from the outside by sending a request message to the X-Pipe daemon.
|
||||
The daemon then always sends a response message.
|
||||
|
||||
- The header information of a message is formatted in the json format.
|
||||
As a result, all data structures exchanged must be serializable/deserializable with jackson.
|
||||
|
||||
- Both the requests and responses can optionally include content in a body.
|
||||
A body is initiated with two new lines (`\n`).
|
||||
|
||||
- The body is split into segments of max length `65536`.
|
||||
Each segment is preceded by four bytes that specify the length of the next segment.
|
||||
In case the next segment has a length of less than `65536` bytes, we know that the end of the body has been reached.
|
||||
This way the socket communication can handle payloads of unknown length.
|
||||
|
||||
## Configuration
|
||||
|
||||
The default port used by the beacon implementation of the X-Pipe daemon and APIs is `21721`.
|
||||
It can be changed by passing the property `io.xpipe.beacon.port=<port>` to both the daemon and APIs.
|
||||
#### Custom port
|
||||
|
||||
The default port can be changed by passing the property `io.xpipe.beacon.port=<port>` to both the daemon and APIs.
|
||||
Note that if both sides do not have the same port setting, they won't be able to reach each other.
|
||||
|
||||
#### Custom launch command
|
||||
|
||||
The beacon API also supports launching the daemon automatically in case it is not started yet.
|
||||
By default, it launches the daemon of the local X-Pipe installation.
|
||||
It is possible to pass a custom launch command with the property `io.xpipe.beacon.exec=<cmd>`.
|
||||
It is possible to pass a custom launch command with the property `io.xpipe.beacon.customDaemonCommand=<cmd>`
|
||||
and pass arguments to it using the property `io.xpipe.beacon.daemonArgs=<args>`.
|
||||
This allows for a custom launch behaviour in a testing/development environment.
|
||||
Note that the `<cmd>` value has to be a single property string, which can be prone to formatting errors
|
||||
|
||||
By passing the property `io.xpipe.beacon.debugOutput=true`, it is possible to print debug information
|
||||
#### Verbose output
|
||||
|
||||
By passing the property `io.xpipe.beacon.printMessages=true`, it is possible to print debug information
|
||||
about the underlying communications.
|
||||
In case the `io.xpipe.beacon.exec` property is set, the output of the custom exec command can also be
|
||||
In case the `io.xpipe.beacon.printDaemonOutput` property is set, the output of the daemon can also be
|
||||
printed by passing the property `io.xpipe.beacon.debugExecOutput=true`.
|
||||
|
||||
#### Daemon debug mode
|
||||
|
||||
In case the daemon is started by the beacon, it is possible to customize in which mode the daemon will start up.
|
||||
By passing the property `io.xpipe.beacon.launchDebugDaemon=true`, the daemon is started in debug mode,
|
||||
i.e. will log more information and enable a few other options.
|
||||
By passing the property `io.xpipe.beacon.attachDebuggerToDaemon=true`, it is possible to launch a daemon
|
||||
in a mode where it is waiting to attach to a debugger first prior to starting up.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,20 +1,28 @@
|
|||
[](https://maven-badges.herokuapp.com/maven-central/io.xpipe/core)
|
||||
[](https://javadoc.io/doc/io.xpipe/core)
|
||||
[](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-core)
|
||||
[](https://javadoc.io/doc/io.xpipe/xpipe-core)
|
||||
|
||||
## X-Pipe Core
|
||||
|
||||
The X-Pipe core module contains all the shared core classes used by the API, beacon, and daemon implementation.
|
||||
It contains the following packages:
|
||||
|
||||
The main component is the [data package](src/main/java/io/xpipe/core/data).
|
||||
It contains all definitions of the internal X-Pipe data model and all IO functionality for these data structures.
|
||||
- [charsetter](src/main/java/io/xpipe/core/charsetter): Classes for handling all things charset
|
||||
related such as detection and handling of data streams with BOMs.
|
||||
|
||||
The [source package](src/main/java/io/xpipe/core/source) contains the basic data source classes,
|
||||
which are used by every data source implementation.
|
||||
- [data](src/main/java/io/xpipe/core/data): Contains all definitions of the
|
||||
internal X-Pipe data model and all the IO functionality to read and write these data structures.
|
||||
For more information, see [X-Pipe data model](https://xpipe-io.readthedocs.io/en/latest/dev/model.html)
|
||||
|
||||
The [store package](src/main/java/io/xpipe/core/store) contains the basic data store classes,
|
||||
which are used by every data store implementation.
|
||||
- [dialog](src/main/java/io/xpipe/core/dialog): In API to create server/daemon side CLI dialogs.
|
||||
These are used by extensions for data source and data store configuration from the command line.
|
||||
|
||||
- [source](src/main/java/io/xpipe/core/source): The basic data source classes that are used by every data source implementation.
|
||||
|
||||
- [store](src/main/java/io/xpipe/core/store): The basic data store classes that are used by every data store implementation.
|
||||
|
||||
- [util](src/main/java/io/xpipe/core/source): A few utility classes for serialization and more.
|
||||
|
||||
Every class is expected to be potentially used in the context of files and message exchanges.
|
||||
As a result, all data structures exchanged must be serializable/deserializable with jackson.
|
||||
As a result, essentially all objects must be serializable/deserializable with jackson.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,18 +1,7 @@
|
|||
[](https://maven-badges.herokuapp.com/maven-central/io.xpipe/extension)
|
||||
[](https://javadoc.io/doc/io.xpipe/extension)
|
||||
[](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-extension)
|
||||
[](https://javadoc.io/doc/io.xpipe/xpipe-extension)
|
||||
|
||||
## X-Pipe Extension API
|
||||
|
||||
The X-Pipe extension API allows you to create extensions of any kind for X-Pipe.
|
||||
This includes:
|
||||
|
||||
- Custom data stores, including configuration GUI and CLI
|
||||
- Custom data sources, including configuration GUI and CLI
|
||||
- Custom preferences entries
|
||||
|
||||
### Custom data sources
|
||||
|
||||
A custom data source type can be implemented by creating a custom
|
||||
[DataSourceProvider](src/main/java/io/xpipe/extension/DataSourceProvider.java).
|
||||
This provider contains all the information required for proper handling of your custom data sources,
|
||||
whether you access it from the CLI, any API, or the X-Pipe commander gui.
|
||||
For more information, see [X-Pipe extension development](https://xpipe-io.readthedocs.io/en/latest/dev/extensions/index.html).
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ dependencies {
|
|||
compileOnly 'net.synedra:validatorfx:0.3.1'
|
||||
compileOnly 'org.junit.jupiter:junit-jupiter-api:5.9.0'
|
||||
compileOnly 'com.jfoenix:jfoenix:9.0.10'
|
||||
compileOnly 'org.controlsfx:controlsfx:11.1.1'
|
||||
compileOnly 'org.controlsfx:controlsfx:11.1.2'
|
||||
compileOnly 'org.apache.commons:commons-lang3:3.12.0'
|
||||
|
||||
if (findProject(':fxcomps') != null) {
|
||||
|
|
|
|||
1
misc/changelogs/0.0.2.1.txt
Normal file
1
misc/changelogs/0.0.2.1.txt
Normal file
|
|
@ -0,0 +1 @@
|
|||
Full support for remote shell connections
|
||||
Loading…
Reference in a new issue