diff --git a/README.md b/README.md index 4bbdebbee..6842a2b48 100644 --- a/README.md +++ b/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. diff --git a/api/README.md b/api/README.md index 005798644..79882626c 100644 --- a/api/README.md +++ b/api/README.md @@ -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). \ No newline at end of file diff --git a/beacon/README.md b/beacon/README.md index 32f8c1a6e..a04561bdc 100644 --- a/beacon/README.md +++ b/beacon/README.md @@ -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. -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=` to both the daemon and APIs. +#### Custom port + +The default port can be changed by passing the property `io.xpipe.beacon.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=`. +It is possible to pass a custom launch command with the property `io.xpipe.beacon.customDaemonCommand=` +and pass arguments to it using the property `io.xpipe.beacon.daemonArgs=`. This allows for a custom launch behaviour in a testing/development environment. Note that the `` 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. + + + diff --git a/core/README.md b/core/README.md index 978f42c18..263238d6e 100644 --- a/core/README.md +++ b/core/README.md @@ -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. diff --git a/extension/README.md b/extension/README.md index b7b2739aa..4df54afec 100644 --- a/extension/README.md +++ b/extension/README.md @@ -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). diff --git a/extension/build.gradle b/extension/build.gradle index 6bf9bd8ae..00f37a661 100644 --- a/extension/build.gradle +++ b/extension/build.gradle @@ -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) { diff --git a/misc/changelogs/0.0.2.1.txt b/misc/changelogs/0.0.2.1.txt new file mode 100644 index 000000000..0418b8feb --- /dev/null +++ b/misc/changelogs/0.0.2.1.txt @@ -0,0 +1 @@ +Full support for remote shell connections \ No newline at end of file