FDC3 3.0.0 Java Implementation With WSCP Support

.gitignore

@@ -13,3 +13,13 @@ docs/contributing.md
 
 # We use YARN
 website/package-lock.json
+
+# Maven target
+target/
+
+# Eclipse Ignore
+.classpath
+.project
+.settings/*
+*/.settings
+fdc3-java-api.code-workspace

.vscode/launch.json

@@ -0,0 +1,22 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "java",
+            "name": "Current File",
+            "request": "launch",
+            "mainClass": "${file}",
+            "vmArgs": [
+                "-Dfdc3.log.level=DEBUG",
+                "-DFDC3_WEBSOCKET_URL=http://localhost:8090/remote/user-fce30a8d-95eb-4fb4-b34d-27ce9fdb10df/87664652dcaedaa4"
+            ]
+        },
+        {
+            "type": "java",
+            "name": "Attach to Maven Debug (port 5005)",
+            "request": "attach",
+            "hostName": "localhost",
+            "port": 5005
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+    "[java]": {
+        "editor.formatOnSave": false,
+        "editor.formatOnPaste": false,
+        "editor.formatOnType": false
+    },
+    "java.format.enabled": false
+}

README.md

@@ -1,108 +1,156 @@
-![badge-labs](https://user-images.githubusercontent.com/327285/230928932-7c75f8ed-e57b-41db-9fb7-a292a13a1e58.svg)
+[![FINOS - Incubating](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-incubating.svg)](https://community.finos.org/docs/governance/Software-Projects/stages/incubating)
 
 # FDC3 Java API
 
-Standardized Java API to enable integration of FDC3 for Java Desktop Applications.
+A Java implementation of the [FDC3 Standard](https://fdc3.finos.org/) enabling Java desktop applications to interoperate with other FDC3-enabled applications via the [Desktop Agent Communication Protocol (DACP)](https://fdc3.finos.org/docs/api/specs/desktopAgentCommunicationProtocol).
 
-## Installation & Development Setup
+```mermaid
+sequenceDiagram
+    participant Sail as FDC3 Sail
+    participant App as Java App
 
-Prerequisite: Java 11
+    Note over Sail: Add connectionUrl to App Directory for native app
+    Note over Sail: Display WebSocket URL in UI
+    Sail-->>App: connectionUrl (advertised in UI for user to copy)
+    Note over App: Obtain webSocketUrl, build GetAgentParams
 
-#### FDC3 Java API
+    App->>Sail: WebSocket connect
+    Sail->>App: Connection accepted
+    App->>Sail: WCP4ValidateAppIdentity (identityURL: native)
+    Sail->>App: WCP5ValidateAppIdentityResponse (appId, instanceId, instanceUuid)
+    Note over App: Store appId, instanceId, instanceUuid for reconnection
 
-In a new terminal, navigate to the `fdc3api` directory
-
-Build Project
-
-```sh
-mvn clean compile
+    loop DACP message exchange
+        App->>Sail: broadcastRequest, addContextListenerRequest, etc.
+        Sail->>App: broadcastEvent, intentEvent, heartbeatEvent, etc.
+    end
 ```
 
-#### FDC3 Container
+**App Identity flow:** Sail adds a `connectionUrl` (WebSocket URL) to each native app's entry in the App Directory and displays it in the Sail UI so the user can copy it (or provide it via config/launch params). The Java app uses this URL in `GetAgentParams`. For a new connection, the app sends `WCP4ValidateAppIdentity` with `identityURL: "native"`. Sail matches this to the App Directory, assigns an `appId`, and returns `instanceId` and `instanceUuid` in `WCP5ValidateAppIdentityResponse`. The app stores these (via `getInfo()`) for reconnection. After handshake, all FDC3 API calls flow as DACP messages over the WebSocket.
 
-In a new terminal, navigate to the `fdc3container` directory
+## Overview
 
-Install Dependencies
+This project provides:
 
-```sh
-npm i
-```
+- **FDC3 Standard API interfaces** — Java equivalents of the FDC3 TypeScript API
+- **Desktop Agent Proxy** — Client-side implementation that communicates with a Desktop Agent over WebSocket
+- **GetAgent factory** — Simple entry point for connecting to a Desktop Agent
+- **Cucumber testing framework** — Shared step definitions for conformance testing against the official FDC3 feature files
 
-Run Application
+## Modules
 
-```sh
-npm start
-```
+| Module             | Description                                                                     |
+| ------------------ | ------------------------------------------------------------------------------- |
+| `fdc3-standard`    | Core FDC3 API interfaces (`DesktopAgent`, `Channel`, `Context`, `Intent`, etc.) |
+| `fdc3-schema`      | Generated schema types and JSON conversion utilities                            |
+| `fdc3-context`     | Context type conversion utilities                                               |
+| `fdc3-agent-proxy` | `DesktopAgentProxy` implementation using DACP messaging                         |
+| `fdc3-get-agent`   | `GetAgent` factory for obtaining a `DesktopAgent` connection via WebSocket      |
 
-Runs on <localhost:8080>
+## Requirements
 
-#### Client
+- Java 11 or later
+- Maven 3.6+
+- A running FDC3 Desktop Agent that supports the [Desktop Agent Communication Protocol](https://fdc3.finos.org/docs/api/specs/desktopAgentCommunicationProtocol) (e.g., [FDC3 Sail](https://github.com/finos/FDC3-Sail))
 
-In a new terminal, navigate to the `client` directory
+## Installation
 
-Build Project:
+### Building from Source
 
 ```sh
-mvn clean compile package
+mvn clean install
 ```
 
-Run the executable from Target directory
+This will download the schemas for the DACP / WCP / Contexts from NPM as it runs.  However, you can also run like this:
 
 ```sh
-java -jar <Project.baseDirectory>\client\target\client-1.0.0-SNAPSHOT.jar
-  ```
+mvn clean install -Plocal
+```
 
-#### Stock Search React Receiver Application
+which will use local schemas inside the `src/main/schemas-temp` directories.  This is a temporary feature for unreleased versions of FDC3.
 
-In a new terminal, navigate to the `fdcreceiver-react-trade-app` directory
+### Maven Dependency
 
-Install Dependencies
+Once published, add to your `pom.xml`:
 
-```sh
-npm i
+```xml
+<dependency>
+    <groupId>org.finos.fdc3</groupId>
+    <artifactId>fdc3-get-agent</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+</dependency>
 ```
 
-Run Application
+## Usage
 
-```sh
-npm start
-```
+### Connecting to a Desktop Agent
+
+````java
+import org.finos.fdc3.getagent.GetAgent;
+import org.finos.fdc3.getagent.GetAgentParams;
+import org.finos.fdc3.api.DesktopAgent;
+import java.util.UUID;
 
-Runs on <localhost:3000>
+// Connect to a Desktop Agent via WebSocket
+GetAgentParams params = GetAgentParams.builder()
+    .webSocketUrl("ws://localhost:4475")           // Desktop Agent WebSocket URL (required)
+    .instanceId(desktopAgentProvidedInstanceId)    // Unique instance ID (required)
+    .instanceUuid(desktopAgentProvidedInstanceUuid)// Shared secret UUID (required)
+    .channelSelector(myChannelSelector)            // Optional: custom ChannelSelector
+    .intentResolver(myIntentResolver)              // Optional: custom IntentResolver
+    .build();
 
-## Usage with the Current State of this Repo
+DesktopAgent agent = GetAgent.getAgent(params).toCompletableFuture().get();
 
-With the goal of our use case being to enable integration of FDC3 for Java Desktop Applications, we developed the Java API in addition to several simple applications that demonstrate its functionality and potential. The components we developed are as follows:
+### Configuration via System Properties
 
-* Java API - Our implementation of the Java API. Located in `fdc3api`
-* Java Swing Sender - Client application to place orders. Located in `client`
-* Adapter - the OpenFin Adapter. Located in `openfin-fdc3-adapter`
-* Trade App - React based application enabled for receiving trade context from the sender. Located in `fdcreceiver-react-trade-app`
-* FDC3 Container - OpenFin based container hosting the receiver environment. Located in `fdc3container`
+The following system properties can be used to provide default values for `GetAgentParams`.
+Values set via the builder will override these defaults.
 
-As you interact with these applications, you will see our API in action. For example, say the user were to send the instruments from the Java Swing blotter, this action would then be reflected across the receiving web applications. In addition, we implemented a feature to allow the user to select what channel they are listening on to demonstrate the potential of our API.
+| System Property       | Description                                      |
+| --------------------- | ------------------------------------------------ |
+| `FDC3_WEBSOCKET_URL`  | Default WebSocket URL for the Desktop Agent      |
+| `FDC3_INSTANCE_ID`    | Instance ID for the application instance (if reconnecting)|
+| `FDC3_INSTANCE_UUID`  | Instance ID UUID (shared secret) (if reconnecting)            |
 
-![Demo Screenshot](readme-images/demo_screenshot.png)
+This allows for simplified configuration when these values are provided externally:
 
-## Usage in a Business Environment
+```java
+// If system properties are set, the builder can be used with minimal configuration
+// e.g., java -DFDC3_WEBSOCKET_URL=ws://localhost:4475 -DFDC3_INSTANCE_ID=my-app ...
+GetAgentParams params = GetAgentParams.builder()
+    .channelSelector(myChannelSelector)  // Only set optional overrides
+    .build();
+```
+
+### Broadcasting Context
 
-Some firms have existing Java desktop applications, and they want to use FDC3 to integrate with other apps that use JavaScript or other technologies.
+```java
+// Create and broadcast a context
+Context contact = new Contact("jane@example.com", "Jane Smith");
+agent.broadcast(contact);
+````
 
-For example, a buy-side trader using an internal Java order management system selects an order on their blotter and wants to view related analytics in an external JavaScript app provided by a broker.
+### Listening for Context
 
-This API will provide a standardized API for Java app developers to use, making it easier to switch the underlying technology that provides the FDC3 communication if required. By leveraging our FDC3 Java API in existing apps, developers will be able to create a user friendly workflow that favors shared context between applications as opposed to manual repetition by the user.
+```java
+// Add a context listener
+agent.addContextListener("fdc3.contact", context -> {
+    System.out.println("Received contact: " + context);
+});
+```
 
-## Roadmap
+### Raising Intents
 
-1. Robust testing
-2. Acceptance as a FINOS standard
-3. The FDC3 Java API is leveraged in a production environment
-4. Review with OpenFin the FDC3 features not currently supported by their Java API. Discuss if they would be willing to implement this FDC3 Java API directly instead of using an adapter.
-5. If possible, write a fully open-source implementation of the API without any dependency on a specific desktop agent vendor. This may be possible using websocket with the new desktop agent bridging spec.
+```java
+// Raise an intent (null app lets the resolver choose)
+IntentResolution resolution = agent.raiseIntent("ViewChart", instrument, null)
+    .toCompletableFuture().get();
+```
 
 ## Contributing
 
-1. Fork it (<https://github.com/finos-labs/fdc3-java-api/fork>)
+1. Fork the repository (<https://github.com/finos/fdc3-java-api/fork>)
 2. Create your feature branch (`git checkout -b feature/fooBar`)
 3. Read our [contribution guidelines](.github/CONTRIBUTING.md) and [Community Code of Conduct](https://www.finos.org/code-of-conduct)
 4. Commit your changes (`git commit -am 'Add some fooBar'`)
@@ -111,11 +159,11 @@ This API will provide a standardized API for Java app developers to use, making
 
 _NOTE:_ Commits and pull requests to FINOS repositories will only be accepted from those contributors with an active, executed Individual Contributor License Agreement (ICLA) with FINOS OR who are covered under an existing and active Corporate Contribution License Agreement (CCLA) executed with FINOS. Commits from individuals not covered under an ICLA or CCLA will be flagged and blocked by the FINOS Clabot tool. Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA.
 
-*Need an ICLA? Unsure if you are covered under an existing CCLA? Email [help@finos.org](mailto:help@finos.org)*
+_Need an ICLA? Unsure if you are covered under an existing CCLA? Email [help@finos.org](mailto:help@finos.org)_
 
 ## License
 
-Copyright 2023 Wellington Management Company LLP
+Copyright 2026 Fintech Open Source Foundation (FINOS)
 
 Distributed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
 

TODO.md

@@ -0,0 +1,3 @@
+## TODO
+
+- Download Proxy feature files from npm (once they are published there)