Documentation/faq java ammendment

docs/troubleshooting_and_faq/build.md

@@ -1,33 +1,53 @@
 # mp-build
 
-
-### mp-build returns 'Unable to build pak file'
+### mp-build returns 'Unable to build container'
 
 In most cases, this error indicates issues with building the container image. The most probable causes are:
 
 1. Unknown Instruction :
+      ```
+      mp-build
+      Building adapter [Finished]
+      Unable to build container 
+      ERROR: Unable to build Docker file at /Users/user/code/aria_ops/management-packs/test:
+       {'message': 'dockerfile parse error line 7: unknown instruction: COP'}
 
-  ```
-  mp-build
-  Building adapter [Finished]
-  Unable to build pak file
-  ERROR: Unable to build Docker file at /Users/user/code/aria_ops/management-packs/test:
-   {'message': 'dockerfile parse error line 7: unknown instruction: COP'}
-
-  ```
-2. A command  inside the Dockerfile failed:
-
-  ```
-  mp-build
-  Building adapter [Finished]
-  Unable to build pak file
-  ERROR: Unable to build Docker file at /Users/user/code/management-packs/test:
-   The command '/bin/sh -c pip3 install -r adapter_requirements.txt --upgrade' returned a non-zero code: 1
-  ```
-The solution for case 1 to fix the typo/command by editing the Dockerfile. For case 2, however, the solution might not be evident at first sight. Since the error
-comes from building the image itself, we can run `docker build .` in the project's root directory and look at the stack trace for clues.
+      ```
+2. A command inside the Dockerfile failed:
+
+      ```
+      Building adapter [Finished]
+      Unable to build container
+      ERROR: Unable to build Docker file at /Users/user/code/aria_ops/management-packs/test:
+      The command '/bin/sh -c pip3 install -r adapter_requirements.txt --upgrade' returned a non-zero code: 1
+      Step 1/6 : FROM projects.registry.vmware.com/vmware_aria_operations_integration_sdk/base-adapter:python-0.12.1
+      ---> 162815abfec9
+
+      Step 2/6 : COPY commands.cfg .
+      ---> a30b1027a43c
+
+      Step 3/6 : COPY adapter_requirements.txt .
+      ---> 62ccf9b7b89d
+
+      Step 4/6 : RUN pip3 install -r adapter_requirements.txt --upgrade
+      ---> Running in 64f44a73a22f
+
+      Defaulting to user installation because normal site-packages is not writeable
+
+      ERROR: Could not find a version that satisfies the requirement vmware-aria-operations-integration-sdk-lib==100 (from versions: 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.4, 0.4.5, 0.4.6, 0.4.7, 0.5.0, 0.6.0, 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.7.4, 0.8.0, 0.8.1)
+
+      ERROR: No matching distribution found for vmware-aria-operations-integration-sdk-lib==100
+
+
+      [notice] A new release of pip available: 22.3.1 -> 23.3
+      [notice] To update, run: pip install --upgrade pip
+      ```
+   The solution is for case 1 to fix the typo/command by editing the Dockerfile.
+   For case 2, however, the solution might not be evident at first sight.
+   Since the error comes from building the image itself,
+   we can run look at the stack trace for clues
+   (the stack trace is the same stack trace generated by docker build command).
 
 ???+ info
 
     For issues regarding mp-build and docker, see [Docker's](docker.md) page.
-

docs/troubleshooting_and_faq/collections.md

@@ -7,33 +7,56 @@ Internal server errors can happen for various reasons; however, the most common
 the adapter's code. Check the server logs for clues about the issue. Sometimes, the problem may be detected using `mp-test` and
 going over the terminal output.
 
+---
 ### Collection returns 'No collection result was found'
 
-`mp-test` runs a series of validations test after collection; if the collection has no results, then each validation step will report the result as missing.
-When a collection result is missing, it usually means an error occurred during collection, but the Adapter handled the error. When the Adapter handles an error,
-the response contains an error message; The console displays the error message. For example:
-
-  ```python
-  def collect(adapter_instance: AdapterInstance) -> CollectResult:
-    result = CollectResult()
-    try:
-      raise Exception("oops")
-
-      #...
-    except Exception as e:
-      logger.error("Unexpected collection error")
-      logger.exception(e)
-      result.with_error("Unexpected collection error: " + repr(e))
-      return result
-  ```
-
-This code will output
-
-  ```
+`mp-test` runs a series of validations test after a collection; if the collection has no results, then each validation
+step will report the result as missing.
+When a collection result is missing, it usually means an error occurred during a collection,
+but the Adapter handled the error.
+When the Adapter handles an error, the response contains an error message; The console displays the error message.
+For example:
+
+=== "Python Adapter Library"
+
+      ```python linenums="1"
+      def collect(adapter_instance: AdapterInstance) -> CollectResult:
+        result = CollectResult()
+        try:
+          raise Exception("oops!")
+
+          #...
+        except Exception as e:
+          logger.error("Unexpected collection error")
+          logger.exception(e)
+          result.with_error(f"Unexpected collection error: '{e}'")
+          return result
+      ```
+
+=== "Java Adapter Library"
+
+      ```python linenums="1"
+      public CollectRestuls collect(AdapterInstance adapterInstance) {
+        CollectResult result = new CollectResult();
+        try{
+          throw new Exception("oops!");
+
+          //...
+        } catch ( Exception  e) {
+          result.with_error("Unexpected collection error: " + "'" + e.getMessage() + "'");
+        }
+
+        return result
+      }
+      ```
+
+will output
+
+  ``` hl_lines="4"
   Building adapter [Finished]
   Waiting for adapter to start [Finished]
   Running Collect [Finished]
-  Collection Failed: Unexpected collection error: Exception('oops')
+  Collection Failed: Unexpected collection error: 'oops!'
 
   Avg CPU %                     | Avg Memory Usage %         | Memory Limit | Network I/O         | Block I/O
   ------------------------------+----------------------------+--------------+---------------------+--------------
@@ -45,18 +68,21 @@ This code will output
   No collection result was found.
   All validation logs written to '/Users/user/management-pack/test-management-pack/logs/validation.log'
   ```
-As seen above, the Exception is mentioned as the reason for the collection error, and the `No collection result was found` message is also shown.
+
+As seen above, the Exception is mentioned as the reason for the collection error, and
+the `No collection result was found` message is also shown.
 Using the collection error message along with the `adapter.log` can help trace the cause of the issue.
 
+---
 ### Is there a way to cache data for subsequent collections?
 
 The containerized adapter does not support caching data between collections.
 
+---
 ### Can I implement on-demand collections?
 
 The containerized adapter does not support on-demand collections.
 
 ???+ info
 
     For issues regarding mp-test and docker, see [Docker's](docker.md) page.
-

docs/troubleshooting_and_faq/docker.md

@@ -1,17 +1,19 @@
 # Docker
 
 
-### When starting Docker, I get 'Permission denied while trying to connect to the Docker daemon'
+### When starting Docker, I get a 'Permission denied while trying to connect to the Docker daemon' message
 
 If you're having trouble getting Docker to run on your system, you can refer to the Docker documentation for instructions
 on how to start Docker on [macOS](https://docs.docker.com/docker-for-mac/install/), [Linux](https://docs.docker.com/desktop/install/debian/#launch-docker-desktop), and [Windows 10 and 11](https://docs.docker.com/desktop/install/windows-install/#start-docker-desktop).
 
-### When starting Docker on Windows, I get 'Cannot connect to Docker daemon'
+---
+### When starting Docker on Windows, I get a 'Cannot connect to Docker daemon' message
 
 If you're having trouble with permissions on a Windows system, you can refer to the Docker documentation for instructions
 on how to [Understand permission requirements for Windows](https://docs.docker.com/desktop/windows/permission-requirements/).
 
-### When using mp-test and mp-build, I get a "Cannot connect to the Docker daemon" error
+---
+### When using mp-test and mp-build, I get a 'Cannot connect to the Docker daemon' message
 
 There are multiple causes for this error; the most common causes and solutions are:
 
@@ -21,9 +23,9 @@ There are multiple causes for this error; the most common causes and solutions a
     - See Docker's documentation for [troubleshooting the Docker daemon](https://docs.docker.com/config/daemon/troubleshoot/)
 
 2. The Docker daemon is running, but the socket is not open or accessible. Possible solutions are:
-    - Open Docker Desktop application → navigate to Settings on the top right corner (Cog icon) → Advanced (Cogs icon) → make sure "Allow the default Docker socket to be used" is enabled.
+    - Open Docker Desktop application → navigate to Settings in the top right corner 
+    (Cog icon) → Advanced (Cogs icon) → make sure "Allow the default Docker socket to be used" is enabled.
     - Ensure permissions to access the Docker daemon socket are enabled:
         - For [MacOs](https://docs.docker.com/desktop/mac/permission-requirements/)
         - For [Windows](https://docs.docker.com/desktop/windows/permission-requirements/)
-        - FOR [Linux](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
-
+        - For [Linux](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)