Skip to content

Requirements Specification

1. Scope

  • Provide a configurable, reusable client for Odoo XML-RPC API v2, supporting authentication, entity search, read, search_read, create/update/delete, and document-centric operations.
  • Expose higher-level, domain-oriented facades (e.g., Products/Transfers) to simplify business usage.
  • Map Odoo records to TourLinq canonical entities using annotated Java classes.

2. Functional Requirements

  1. Configuration & Bootstrap
    • The client must load properties from TLINQ_HOME/odoo-client.properties and TLINQ_HOME/odoo-server.properties via OdooClientConfig.
    • Must support per-service configuration via properties keys:
      • services.<serviceName>.class (implementation class)
      • services.<serviceName>.model (Odoo model, e.g., res.partner)
      • services.<serviceName>.action (Odoo method, e.g., search, read, search_read, create, write)
    • Must support per-entity configuration and lookups via entities.<entityName>.* keys (e.g., default service names).
  2. Authentication & Session Management
    • Authenticate using Odoo XML-RPC common endpoint and store session in a cache (TlinqClusterCache under userSessions).
    • Provide system session bootstrapped by OdooServiceFactory using odoo.user, odoo.pwd, and keep its token in odoo.session.
    • Expose authenticateUser(user, pwd[, sessionToken]) that returns a session token and stores UserLogin with the Odoo uid.
  3. Service Construction
    • Provide a singleton OdooServiceFactory to create services by name:
      • createService(serviceName, sessionToken) → RemoteServiceI
      • Shorthands to create typed specializations: createSearchService, createReadService, createSearchReadService, createClientService(Class, serviceName, sessionToken)
    • New services must be initialized with server URL /xmlrpc/2/object, DB name, userId and password from the session/config.
  4. Core Operations
    • Search: Build domain filters via SearchDomain, support offset, limit, order, count when applicable.
    • Read: Read fields by IDs, support selecting fields list.
    • Search+Read: Combined query, returns mapped native entities; handle like → ilike normalization.
    • Write: create, write(id, entity), delete(id) using maps generated by entities.
    • Document: Provide OdooDocumentService for document or printout operations (e.g., reading binary fields or triggering server-side actions; details depend on configured action).
  5. Entity Mapping
    • Each native entity extends OdooEntity and is annotated with @TlinqClientEntity("<canonicalClassFQN>").
    • Fields are annotated with @TlinqEntityField to define source Odoo field names, indexes for many2one tuples, readOnly flags, and mapping to canonical field names.
    • Native-to-canonical conversion is handled reflectively by OdooEntity (e.g., toCanonicalList, createCanonicalObject).
  6. Caching
    • A cache manager (OdooCacheManager) initializes a global cache for transfers (XFERCACHE) using StaticMapCache.
    • Product/transfer lookup results (e.g., from OdooProductFacade) must be cached for fast domain operations.
  7. Error Handling & Logging
    • Translate XML-RPC and reflection errors into TlinqClientException with TlinqErr categories.
    • Log failures and critical steps with java.util.logging.
  8. Security
    • Credentials and tokens must be read from secure properties; tokens stored server-side (TlinqClusterCache).
    • Hostname verification is relaxed for localhost in OdooServiceFactory; production deployments should require strict HTTPS hostname verification.
  9. Performance
    • Services should support pagination (offset, limit), field selection, and server-side ordering.
    • Batch read/write operations should be supported via arrays/lists of IDs.
  10. Compatibility
  11. Odoo v12+ XML-RPC v2 endpoints (/xmlrpc/2/common, /xmlrpc/2/object).
  12. Java 11+ environment, compatible with existing TourLinq RemoteServiceI abstractions.

3. Non-Functional Requirements

  • Reliability: Retriable operations can be introduced at factory or service layer (currently not implemented).
  • Observability: Log session creation and service invocation errors.
  • Configurability: No code changes required to bind a service name to a given model/action; driven by properties.
  • Extensibility: New entity/services added with minimal boilerplate via annotations and property bindings.

4. Configuration Keys (mandatory/typical)

  • Core:
    • odoo.server, odoo.db, odoo.user, odoo.pwd, odoo.userId (assigned after login), odoo.session
    • odoo.format.date, odoo.format.datetime
  • Services:
    • services.<name>.class, services.<name>.model, services.<name>.action
  • Entities:
    • entities.<name>.searchservice, entities.<name>.readservice, entities.<name>.getservice

5. Acceptance Criteria

  • Successful bootstrap: OdooPlugin.initializePlugin() initializes OdooServiceFactory and OdooCacheManager without errors.
  • Authentication: OdooServiceFactory.connected() returns true; system session token available.
  • End-to-end flow: Using OdooProductFacade, client can search and read products and transfers, with results mapped to native and canonical entities.
  • Errors surfaced as TlinqClientException with meaningful messages.