Java: merge java-development to main (#6440)

### Motivation and Context

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->

### Description

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [ ] The code builds clean without any errors or warnings
- [ ] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [ ] All unit tests pass, and I have added new tests where possible
- [ ] I didn't break anyone 😄

.editorconfig

@@ -413,10 +413,10 @@ resharper_arrange_this_qualifier_highlighting = warning # Resharper's "Arrange '
 [*.java]
 charset = utf-8
 end_of_line = lf
-indent_size = 2
+indent_size = 4
 indent_style = space
 insert_final_newline = false
-tab_width = 2
+tab_width = 4
 ij_formatter_off_tag = @formatter:off
 ij_formatter_on_tag = @formatter:on
 ij_smart_tabs = false

.github/workflows/java-build.yml

@@ -1,5 +1,7 @@
 name: Build Java Semantic Kernel
 
+# Triggers the workflow on manual dispatch, push, and pull request events
+# for the specified branches and paths
 on:
   workflow_dispatch:
   push:
@@ -15,6 +17,7 @@ permissions:
   contents: read
 
 jobs:
+  # Determines if Java files have changed
   paths-filter:
     runs-on: ubuntu-latest
     outputs:
@@ -28,21 +31,22 @@ jobs:
             java:
               - 'java/**'
               - '**/java/**'
-      # run only if 'java' files were changed
       - name: java tests
         if: steps.filter.outputs.java == 'true'
         run: echo "Java file"
-      # run only if not 'java' files were changed
       - name: not java tests
         if: steps.filter.outputs.java != 'true'
         run: echo "NOT java file"
+
+  # Builds and tests the Java project
   java-build:
     runs-on: ubuntu-latest
     needs: paths-filter
     if: needs.paths-filter.outputs.javaChanges == 'true'
     strategy:
       fail-fast: false
       matrix:
+        # Defines a matrix strategy for JDK versions 8 and 17
         java-versions: [8, 17]
 
     name: Java CI on JDK${{ matrix.java-versions }}
@@ -63,20 +67,24 @@ jobs:
             echo "JDK_VERSION=$version" >> $GITHUB_OUTPUT
           fi
 
+      # Sets up the specified JDK version from the matrix
       - uses: actions/setup-java@v4
         with:
           java-version: ${{ steps.set-jdk.outputs.JDK_VERSION }}
           distribution: microsoft
           cache: maven
 
+      # Builds the project with Maven using the matrix JDK version
       - name: Build with Maven
         run: ./mvnw -B -Pbug-check -DskipTests -Pcompile-jdk${{ matrix.java-versions }} clean install --file pom.xml
         working-directory: java
 
+      # Runs tests with Maven using the matrix JDK version
       - name: Run tests
         run: ./mvnw -B -Pbug-check -Pcompile-jdk${{ matrix.java-versions }} test --file pom.xml
         working-directory: java
 
+      # Uploads test artifacts for each JDK version
       - uses: actions/upload-artifact@v2
         if: always()
         with:

.github/workflows/java-integration-tests.yml

@@ -70,8 +70,9 @@ jobs:
           cache: maven
 
       - name: Build with Maven
-        run: ./mvnw -B -Pbug-check -DskipTests -Pcompile-jdk${{ matrix.java-versions }} clean install --file pom.xml
+        run: ./mvnw -B -Pwith-samples -Pbug-check -DskipTests -Pcompile-jdk${{ matrix.java-versions }} clean install --file pom.xml
         working-directory: java
+        if: ${{ matrix.java-versions >= 17 }}
 
       # API tests run on JDK 17+
       - name: Run integration tests

.gitignore

@@ -476,6 +476,9 @@ java/.mvn/wrapper/maven-wrapper.jar
 # Java settings
 conf.properties
 
+# Intellij configuration
+*.iml
+
 # Playwright
 playwright-report/
 

java/CHANGELOG.md

@@ -0,0 +1,29 @@
+# 1.1.3
+
+- Fix bug appending plugin name to tool calls
+- Improve exception handling in OpenAIChatCompletion
+
+# 1.1.2
+
+- Upgrade azure-identity to 1.12.1
+- Remove fixed netty version in bom
+
+# 1.1.1
+
+- Upgrade azure-ai-openai to 1.0.0-beta.8
+
+# 1.1.0
+
+### Breaking Changes
+
+- `ChatHistory` no longer has a default message, see below for more details.
+
+### Api Changes
+  - Allow setting deployment name in addition to modelId on AI services.
+  - Remove default message of "Assistant is a large language model" from ChatHistory
+    - **This is a breaking change if you were relying on the default message in your code**
+  - Add InvocationReturnMode and rework OpenAi chat completion to allow configuring what data is returned from Chat requests
+
+### Other
+- Reorganize example projects and documentation structure.
+- Number of sample updates and bug fixes.

java/PACKAGES.md

@@ -34,121 +34,43 @@ A BOM is provided that can be used to define the versions of all Semantic Kernel
 `semantickernel-api`
 : Package that defines the core public API for the Semantic Kernel for a Maven project.
 
-`semantickernel-core`
-: The internal implementation of the Semantic Kernel API.
-This package contains the core implementation of the Semantic Kernel. This must be made available to the
-application at runtime. Note that these classes are considered internal and should not be used directly by the application. Should they be used directly, it could cause instability in the application as they may change without notice over time.
+## Services
 
-## Connectors
-
-`semantickernel-connectors-ai-openai`
+`semantickernel-aiservices-openai`
 : Provides a connector that can be used to interact with the OpenAI API.
 
-### Memory Connectors
-
-#### JDBC Memory Connectors
-
-`semantickernel-connectors-memory-jdbc`
-: A package that serves as a parent for all JDBC based connectors, adding a new JDBC database should be a matter of extending the classes within this module.
-
-Provides a memory connector that can be used to interact with a JDBC database.
-- `semantickernel-connectors-memory-sqlite`
-- `semantickernel-connectors-memory-postgresql`
-- `semantickernel-connectors-memory-mysql`
-
-`semantickernel-connectors-memory-azurecognitivesearch`
-: Provides a memory connector for using Azure Cognitive Search as the memory provider for an application.
-
-### Miscellaneous Packages
-
-`semantickernel-planners`
-: Implementations of various planners that can be used in the execution of semantic functions.
-
-`semantickernel-plugin-core`
-: Several example plugins, many of which are used in the [Semantic Kernel for Java samples](./samples).
-
-`semantickernel-gpt3-tokenizer`
-: A tokenizer that can be used to tokenize text for use with GPT-3. Can be used to estimate cost.
-
-
 ## Example Configurations
 
 ### Example: OpenAI + SQLite
 
-POM XML for a simple project that uses OpenAI for text or chat completion with an SQLite database as the memory provider.
+POM XML for a simple project that uses OpenAI.
 
 ```xml
-<dependencyManagement>
+
+<project>
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>com.microsoft.semantic-kernel</groupId>
+                <artifactId>semantickernel-bom</artifactId>
+                <version>${semantickernel.version}</version>
+                <scope>import</scope>
+                <type>pom</type>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
     <dependencies>
         <dependency>
             <groupId>com.microsoft.semantic-kernel</groupId>
-            <artifactId>semantickernel-bom</artifactId>
-            <version>${semantickernel.version}</version>
-            <scope>import</scope>
-            <type>pom</type>
+            <artifactId>semantickernel-api</artifactId>
         </dependency>
-    </dependencies>
-</dependencyManagement>
-<dependencies>
-    <dependency>
-        <groupId>com.microsoft.semantic-kernel</groupId>
-        <artifactId>semantickernel-api</artifactId>
-    </dependency>
-    <dependency>
-        <groupId>com.microsoft.semantic-kernel</groupId>
-        <artifactId>semantickernel-core</artifactId>
-        <scope>runtime</scope>
-    </dependency>
-    <dependency>
-        <groupId>com.microsoft.semantic-kernel</groupId>
-        <artifactId>semantickernel-connectors-ai-openai</artifactId>
-    </dependency>
-    <dependency>
-        <groupId>com.microsoft.semantic-kernel</groupId>
-        <artifactId>semantickernel-connectors-memory-sqlite</artifactId>
-    </dependency>
-</dependencies>
-```
-
-### Example: Planner using Open AI + Cognitive Search
-
-The POM XML content for a project that uses Open AI for planning, using Azure Cognitive Search as the memory provider.
-
-```xml
-<dependencyManagement>
-    <dependencies>
         <dependency>
             <groupId>com.microsoft.semantic-kernel</groupId>
-            <artifactId>semantickernel-bom</artifactId>
-            <version>${semantickernel.version}</version>
-            <scope>import</scope>
-            <type>pom</type>
+            <artifactId>semantickernel-connectors-ai-openai</artifactId>
         </dependency>
     </dependencies>
-</dependencyManagement>
-<dependencies>
-    <dependency>
-        <groupId>com.microsoft.semantic-kernel</groupId>
-        <artifactId>semantickernel-api</artifactId>
-    </dependency>
-    <dependency>
-        <groupId>com.microsoft.semantic-kernel</groupId>
-        <artifactId>semantickernel-core</artifactId>
-        <scope>runtime</scope>
-    </dependency>
-    <dependency>
-        <groupId>com.microsoft.semantic-kernel</groupId>
-        <artifactId>semantickernel-connectors-ai-openai</artifactId>
-    </dependency>
-    <dependency>
-        <groupId>com.microsoft.semantic-kernel</groupId>
-        <artifactId>semantickernel-connectors-memory-azurecognitivesearch</artifactId>
-    </dependency>
-    <dependency>
-        <groupId>com.microsoft.semantic-kernel</groupId>
-        <artifactId>semantickernel-planners</artifactId>
-    </dependency>
-</dependencies>
+</project>
 ```
 
 
+

java/README.md

@@ -1,44 +1,60 @@
 # Semantic Kernel for Java
 
-Semantic Kernel (SK) is a lightweight foundation that lets you easily mix conventional programming languages with the latest in
+Semantic Kernel (SK) is a lightweight foundation that lets you easily mix conventional programming languages with the
+latest in
 Large Language Model (LLM) AI "prompts" with templating, chaining, and planning capabilities out-of-the-box.
 
 To learn more about Microsoft Semantic Kernel, visit
 the [Microsoft Semantic Kernel documentation](https://learn.microsoft.com/en-us/semantic-kernel/whatissk).
 
-The Microsoft Semantic Kernel for Java is a library that implements the key concepts and foundations of Microsoft Semantic Kernel. It is designed
-to be used in Java applications in both client (desktop, mobile, CLIs) and server environments in an idiomatic way, and to be easily integrated with other Java libraries
+The Microsoft Semantic Kernel for Java is a library that implements the key concepts and foundations of Microsoft
+Semantic Kernel. It is designed
+to be used in Java applications in both client (desktop, mobile, CLIs) and server environments in an idiomatic way, and
+to be easily integrated with other Java libraries
 and frameworks.
 
+## Quickstart
+
+To get an idea of how to use the Semantic Kernel for Java, you can check
+the [syntax-examples](samples/semantickernel-concepts/semantickernel-syntax-examples/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples) folder for
+examples of common AI-enabled scenarios.
+
 ## Get started
 
 To run the LLM prompts and semantic functions in this kernel, make sure you have
-an [Open AI API Key](https://platform.openai.com)
+an [Open AI API Key](https://platform.openai.com/)
 or [Azure Open AI service key](https://learn.microsoft.com/azure/cognitive-services/openai/).
 
 ### Requirements
 
 To build the Semantic Kernel for Java, you will need:
 
 - **Required**:
-  - [OpenJDK 17](https://microsoft.com/openjdk/) or newer
+    - [OpenJDK 17](https://microsoft.com/openjdk/) or newer
 
 ### Build the Semantic Kernel
 
 1. Clone this repository
 
-        git clone -b java-development https://github.com/microsoft/semantic-kernel/
+        git clone -b java-v1 https://github.com/microsoft/semantic-kernel/
 
 2. Build the project with the Maven Wrapper
 
         cd semantic-kernel/java
         ./mvnw install
 
+3. (Optional) To run a FULL build including static analysis and end-to-end tests that might require a valid OpenAI key,
+   run the following command:
+
+        ./mvnw clean install -Prelease,bug-check,with-samples
+
 ## Using the Semantic Kernel for Java
 
-The library is organized in a set of dependencies published to Maven Central. For a list of the Maven dependencies and how to use each of them, see [PACKAGES.md](PACKAGES.md).
+The library is organized in a set of dependencies published to Maven Central. For a list of the Maven dependencies and
+how to use each of them, see [PACKAGES.md](PACKAGES.md).
 
-Alternatively, check the `samples` folder for examples of common AI-enabled scenarios implemented with Semantic Kernel for Java.
+Alternatively, check the `samples` folder for examples of common AI-enabled scenarios implemented with Semantic Kernel
+for Java.
 
 ## Discord community
 
@@ -52,13 +68,13 @@ and get help from the community. We have a `#java` channel for Java-specific que
 The project may contain end-to-end tests that require an OpenAI key to run. To run these tests locally, you
 will need to set the following environment variable:
 
-- `OPENAI_API_KEY` - the OpenAI API key.
+- `CLIENT_KEY` - the OpenAI API key.
 
 If you are using Azure OpenAI, you will also need to set the following environment variables:
 
-- `AZURE_OPENAI_ENDPOINT` - the Azure OpenAI endpoint found in **Keys * Endpoint** section of the Azure OpenAI service.
-- `AZURE_OPENAI_API_KEY` - the Azure OpenAI API key found in **Keys * Endpoint** section of the Azure OpenAI service.
-- `AZURE_OPENAI_DEPLOYMENT_NAME` - the custom name you chose for your deployment when you deployed a model. It can be
+- `CLIENT_ENDPOINT` - the Azure OpenAI endpoint found in **Keys * Endpoint** section of the Azure OpenAI service.
+- `AZURE_CLIENT_KEY` - the Azure OpenAI API key found in **Keys * Endpoint** section of the Azure OpenAI service.
+- `MODEL_ID` - the custom name you chose for your deployment when you deployed a model. It can be
   found under **Resource Management > Deployments** in the Azure Portal.
 
 For more information, see the Azure OpenAI documentation
@@ -70,7 +86,7 @@ To run the unit tests only, run the following command:
 
 To run all tests, including integration tests that require an OpenAI key, run the following command:
 
-    ./mvnw verify
+    ./mvnw verify -Prelease,bug-check,with-samples
 
 ### Submitting a pull request
 
@@ -88,7 +104,7 @@ Also ensure that:
 - All new code is covered by unit tests
 - All new code is covered by integration tests
 
-Once your proposal is ready, submit a pull request to the `java-development` branch. The pull request will be reviewed by the
+Once your proposal is ready, submit a pull request to the `java-v1` branch. The pull request will be reviewed by the
 project maintainers.
 
 Make sure your pull request has an objective title and a clear description explaining the problem and solution.