Skip to content

Latest commit

 

History

History
147 lines (113 loc) · 5.36 KB

Contribute.md

File metadata and controls

147 lines (113 loc) · 5.36 KB
Raw

Developer Corner

We gather here info and tips for current and future developers of the Java SDK.

Regenerate the SDK

We use swagger-codegen to generate the java client.

For the time being, we rather clone the repository in a temp location to generate the new version of the code and then replace the com.pydio.cells.openapi package in the local repository, to avoid polluting the main repo with autogenerated files (gradle, doc, config files...)

With OpenAPI 3

Note: you can check for new release here.

mkdir -p /tmp/forSwagger
cd /tmp/forSwagger
git clone https://github.com/pydio/cells-sdk-java.git
cd cells-sdk-java

GENERATOR_VERSION=7.4.0
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/${GENERATOR_VERSION}/openapi-generator-cli-${GENERATOR_VERSION}.jar -O openapi-generator-cli.jar

(Temporary) a la mano

WARNING: temporary tweak to go on supporting pre-v4 Cells remote servers: After migrating the swagger spec file to v3 yaml format, we manually edit it to re-add a "JobName" body parameters for job requests, otherwise, such request to a v3 server will fail. Typically for v4-beta1, edit at line 3015, add JobName parameter to have:

...
/jobs/user/{JobName}:
  put:
    tags:
      - JobsService
    summary: Create a predefined job to be run directly
    operationId: UserCreateJob
    parameters:
      - name: JobName
        in: path
        description: Name of the job to create in the user space
        required: true
        schema:
          type: string
    requestBody:
      content:
        application/json:
          schema:
            title: RestUserJobRequest
            type: object
            properties:
              ### Add the 3 lines below
              JobName:
                title: Also add JobName in body to keep backward compatibility with pre v4 versions
                type: string
              ### Until here
              JsonParameters:
                title: Json-encoded parameters for this job
                type: string
      required: true
    responses:
...

Then generate the SDK

# WARNING: Update
SDK_DEFAULT_AGENT="PydioCells/v4.4.0-alpha2/JavaSDK/v0.4.5"

java -jar openapi-generator-cli.jar generate -g java \
    -i ./cellsapi-rest.swagger.yml \
    -o /tmp/forSwagger/cells-sdk-java \
    --invoker-package com.pydio.cells.openapi \
    --api-package com.pydio.cells.openapi.api \
    --model-package com.pydio.cells.openapi.model \
    --http-user-agent ${SDK_DEFAULT_AGENT}

cd $GITPATH/github.com/pydio/cells-sdk-java/src/main/java/com/pydio/cells/
rm -rf ./openapi

mv /tmp/forSwagger/cells-sdk-java/src/main/java/com/pydio/cells/openapi .

# Also copy used sagger file for later references
export CELLS_VERSION=4.4.0-alpha2
cp /tmp/forSwagger/cells-sdk-java/cellsapi-rest.swagger.yml $GITPATH/github.com/pydio/cells-sdk-java/src/main/java/com/pydio/cells/openapi/cellsapi-rest-${CELLS_VERSION}.swagger.yml

# For the record, more details about the possible options:
java -jar swagger-codegen-cli.jar help generate

More tweaks

In Jan. 2023, we should also do the following to finalize SDK generation:

  • Import the project in Android Studio to insure we did not miss any issue
  • Change the javax.ws prefix in the package imports of all class in the openapi package, to import jakarta.ws.rs.core.GenericType rather than javax.ws.rs.core.GenericType: the later package is not maintained anymore.
  • perform a "optimize import" on the com.pydio.cells.openapi client to remove unnecessary warnings.

Developer Tips

Testing OAuth with a Cells server

When testing OAuth and app behaviour on the long run, it might be useful to reduce the validity duration of the JWT token. To do this, simply (backup and) impact your main pydio.json configuration file to add this param:

"services"."pydio.web.oauth"."refreshTokenLifespan":"1m"

For the record, validity duration is expressed as a go duration, and is set by default to 10 minutes (10m).

Various

A list of random resources on the WWW that have helped along the way and are kept here for reference.

  • We use git submodules to ease day-to-day development work, see this interesting post
  • A must read to understand how we manage authentication when target remote server is a Pydio Cells instance.

Temporary Tips

For refactoring

  • We might want to change the package that is used by the swagger generated model and rename packages in a future proof way. We will go trough a temporary phase where we put generated methods at 2 distinct locations while deprecating the legacy one. Some solution can be found in this stackoverflow question