Skip to content

Latest commit

 

History

History
178 lines (139 loc) · 6.32 KB

Contribute.md

File metadata and controls

178 lines (139 loc) · 6.32 KB

Developer Corner

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

Regenerate the SDK

We use the swagger specification that is maintained in Cells main repository and OpenAPI generator to generate a standard Java SDK. The generated code can be found in this module, it should not be manually touched / modified.

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...)

Note: you can check for new release of the generator here.

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

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:

### in old version
...
/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:
...

# In new version with refs
# In components > schemas > RestUserJobRequest at line ±5689
...
RestPutUserMetaTagRequest:
  type: object
  properties:
    Tag:
      title: New tag value
      type: string
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
RoleServiceSetRoleBody:
  type: object
  properties:
...

Then generate the SDK

# WARNING: Update
export CELLS_VERSION=4.9.92-alpha1
SDK_DEFAULT_AGENT="PydioCells/v${CELLS_VERSION}/JavaSDK/v0.5.0"

java -jar openapi-generator-cli.jar generate -g java \
    -i ./cellsapi-rest.swagger.yml -o . \
    --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}

working_dir=$(pwd)

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

mv $working_dir/src/main/java/com/pydio/cells/openapi .

# Also copy used swagger file for later references
cp $working_dir/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 or https://openapi-generator.tech/docs/generators/java/
java -jar swagger-codegen-cli.jar help generate

More tweaks

In Feb 2025 with generator v7.11.0, we also do the followings to finalize a clean SDK:

  • Import the project in Android Studio to ensure we did not miss any issue
  • 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

More tweaks

In Jan. 2023, we also had to do the following to finalize SDK generation: => it seems to not be compulsory anymore in Feb 2025 with generator v7.11.0

  • 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.