CodeMirror/xpipe
1
0
Fork 0
mirror of https://github.com/xpipe-io/xpipe.git synced 2024-07-01 04:21:11 +12:00
Code Issues Packages Projects Releases Wiki Activity

Update readmes

Browse source
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
Show stats Download patch file Download diff file Expand all files Collapse all files

27
README.md
View file

@ -3,28 +3,28 @@
## X-Pipe Java ## 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: This repository contains the following four modules:
- Core - Shared core classes of the Java API, extensions, and the X-Pipe daemon implementation - 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 languages - 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 - 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 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 - Extension - An API to create all different kinds of extensions for the X-Pipe platform
## Installation / Usage ## Installation / Usage
The *core* and *extension* libraries are used in X-Pipe extension development. 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.html) section. 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 The *beacon* module handles all communication and serves as a
reference when implementing an API or program that communicates with the X-Pipe daemon. 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 The *api* module 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. and can also be used to access X-Pipe functionalities from your Java programs.
For setup instructions, see the [X-Pipe Java API Usage]() section. 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 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. 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. 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. 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 To launch the installed daemon, it is required that you either have X-Pipe
is set or the `xpipe` / `xpipe.exe` CLI executable is added to the `PATH` variable. installed or have set the `XPIPE_HOME` environment variable in case you are using a portable version.

13
api/README.md
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) [![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/api/javadoc.svg)](https://javadoc.io/doc/io.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 ## 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 - Create data stores and data sources
- Query and work with the contents of data sources - Query and work with the contents of data sources
- Write and append to data sources - Write data to data sources
## Setup ## Setup
Either install the [dependency](https://maven-badges.herokuapp.com/maven-central/io.xpipe/api) from Maven Central 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 `api.jar`, `core.jar`, and `beacon.jar` 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. 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).

62
beacon/README.md
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) [![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/beacon/javadoc.svg)](https://javadoc.io/doc/io.xpipe/beacon) [![javadoc](https://javadoc.io/badge2/io.xpipe/xpipe-beacon/javadoc.svg)](https://javadoc.io/doc/io.xpipe/xpipe-beacon)
## X-Pipe Beacon ## X-Pipe Beacon
The X-Pipe beacon component is responsible for handling all communications between the X-Pipe daemon 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 and the various programming language APIs and the CLI. It provides an API that supports all kinds
of different operations. 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. ### Inner Workings
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 underlying inter-process communication is realized through
As a result, all data structures exchanged must be serializable/deserializable with jackson. TCP sockets on port `21721` on Windows and `21722` on Linux.
Both the requests and responses can optionally include content in a body. - The data structures and exchange protocols are specified in the
A body is initiated with two new lines (`\n`). [io.xpipe.beacon.exchange package](src/main/java/io/xpipe/beacon/exchange).
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. - Every exchange is initiated from the outside by sending a request message to the X-Pipe daemon.
In case the next segment has a length of less than `65536` bytes, we know that the end of the body has been reached. The daemon then always sends a response message.
This way the socket communication can handle payloads of unknown length.
- 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 ## Configuration
The default port used by the beacon implementation of the X-Pipe daemon and APIs is `21721`. #### Custom port
It can be changed by passing the property `io.xpipe.beacon.port=<port>` to both the daemon and APIs.
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. 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. 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. 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 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. 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`. 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.

26
core/README.md
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) [![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/core/javadoc.svg)](https://javadoc.io/doc/io.xpipe/core) [![javadoc](https://javadoc.io/badge2/io.xpipe/xpipe-core/javadoc.svg)](https://javadoc.io/doc/io.xpipe/xpipe-core)
## X-Pipe Core ## X-Pipe Core
The X-Pipe core module contains all the shared core classes used by the API, beacon, and daemon implementation. 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). - [charsetter](src/main/java/io/xpipe/core/charsetter): Classes for handling all things charset
It contains all definitions of the internal X-Pipe data model and all IO functionality for these data structures. 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, - [data](src/main/java/io/xpipe/core/data): Contains all definitions of the
which are used by every data source implementation. 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, - [dialog](src/main/java/io/xpipe/core/dialog): In API to create server/daemon side CLI dialogs.
which are used by every data store implementation. 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. 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.

17
extension/README.md
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) [![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/extension/javadoc.svg)](https://javadoc.io/doc/io.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 ## X-Pipe Extension API
The X-Pipe extension API allows you to create extensions of any kind for X-Pipe. The X-Pipe extension API allows you to create extensions of any kind for X-Pipe.
This includes: For more information, see [X-Pipe extension development](https://xpipe-io.readthedocs.io/en/latest/dev/extensions/index.html).
- 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.

2
extension/build.gradle
View file

@ -29,7 +29,7 @@ dependencies {
compileOnly 'net.synedra:validatorfx:0.3.1' compileOnly 'net.synedra:validatorfx:0.3.1'
compileOnly 'org.junit.jupiter:junit-jupiter-api:5.9.0' compileOnly 'org.junit.jupiter:junit-jupiter-api:5.9.0'
compileOnly 'com.jfoenix:jfoenix:9.0.10' 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' compileOnly 'org.apache.commons:commons-lang3:3.12.0'
if (findProject(':fxcomps') != null) { if (findProject(':fxcomps') != null) {

1
misc/changelogs/0.0.2.1.txt Normal file
View file

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