Update readmes

This commit is contained in:
Christopher Schnick 2022-11-24 08:43:30 +01:00
parent 2dabc02a3c
commit 7c88e8cd2d
7 changed files with 86 additions and 62 deletions

View file

@ -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.

View file

@ -1,5 +1,5 @@
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.xpipe/api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.xpipe/api)
[![javadoc](https://javadoc.io/badge2/io.xpipe/api/javadoc.svg)](https://javadoc.io/doc/io.xpipe/api)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-api)
[![javadoc](https://javadoc.io/badge2/io.xpipe/xpipe-api/javadoc.svg)](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).

View file

@ -1,40 +1,64 @@
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.xpipe/beacon/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.xpipe/beacon)
[![javadoc](https://javadoc.io/badge2/io.xpipe/beacon/javadoc.svg)](https://javadoc.io/doc/io.xpipe/beacon)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-beacon/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-beacon)
[![javadoc](https://javadoc.io/badge2/io.xpipe/xpipe-beacon/javadoc.svg)](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.
### Inner Workings
- The underlying inter-process communication is realized through
TCP sockets on port `21721` on Windows and `21722` on Linux.
- 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.
- 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.
- 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`.
- 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.

View file

@ -1,20 +1,28 @@
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.xpipe/core/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.xpipe/core)
[![javadoc](https://javadoc.io/badge2/io.xpipe/core/javadoc.svg)](https://javadoc.io/doc/io.xpipe/core)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-core/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-core)
[![javadoc](https://javadoc.io/badge2/io.xpipe/xpipe-core/javadoc.svg)](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.

View file

@ -1,18 +1,7 @@
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.xpipe/extension/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.xpipe/extension)
[![javadoc](https://javadoc.io/badge2/io.xpipe/extension/javadoc.svg)](https://javadoc.io/doc/io.xpipe/extension)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-extension/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.xpipe/xpipe-extension)
[![javadoc](https://javadoc.io/badge2/io.xpipe/xpipe-extension/javadoc.svg)](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).

View file

@ -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) {

View file

@ -0,0 +1 @@
Full support for remote shell connections