Introduction to Voyage

Voyage functions as a lightweight persistence framework designed to bridge object models and NoSQL document stores. Acting as an intermediary layer between application objects and the underlying storage mechanism, it simplifies the process of saving state. Originally derived from collaborative blog entries refined by multiple contributors, the framework evolved into a core component of the Enterprise Pharo documentation suite. To address maintenance complexities inherent in fragmented sources, this documentation consolidates key insights, tutorials, and best practices into a single, actively maintained resource.

Core Architecture

The framework adheres to a strictly object-oriented philosophy, offering a minimalistic API suitable for various development scenarios. Currently, Voyage supports two primary backends:

• In-Memory Store: Ideal for rapid prototyping, initial development phases, or environments where a Pharo image itself serves as the persistent medium.
• MongoDB Backend: Stores entities as JSON-like documents with in a document-oriented database. While distinct from traditional object databases like Gemstone or Magma, this approach leverages the dynamic nature of objects effectively.

To reconcile the impedance mismatch between object graphs and flat documents, Voyage employs a mapper. This component translates instances to documents upon storage and reconstructs them upon retrieval. Although it does not address every known persistence issue found in relational mappings, the document model often provides superior flexibility compared to rigid relational schemas combined with traditional ORMs.

Design Philosophy

The architecture is driven by several fundamental principles aimed at reducing cognitive load and improving reliability:

• Simplicity: Minimizes the amount of boilerplate code developers must define.
• Identity Preservation: Ensures that reloaded instances maintain their original identity, preventing inconsistencies.
• Error Management: Includes robust mechanisms for handling exceptions during persistence operations.
• Resource Efficiency: Implements connection pooling to reduce network overhead and communication costs.

Voyage does not enforce a proprietary query language. Instead, it delegates querying to the native capabilities of the backend (e.g., MongoDB's query syntax). Queries can be constructed using blocks or expressed as JSON dictionaries, leveraging the underlying data interchange format.

Documentation Structure

The available documentation is organized to guide users from basic usage to advanced configuration:

• A beginner-friendly tutorial for getting started quickly.
• A comprehensive review of the public API.
• A collection of tips and tricks for common challenges.

Dependency Management

To integrate persistence capabilities, specifically MongoDB support, dependencies must be loaded into the workspace. Historically, Gofer was utilized, though Metacello is the recommended modern approach.

Using Gofer (Legacy Method):

Gofer new
    repository: 'http://smalltalkhub.com/mc/estebanlm/Voyage/main';
    package: 'VoyageMongo';
    load.

Using Metacello (Recommended):

Metacello new
    baseline: 'Voyage';
    repository: 'github://pharo-nosql/voyage/mc';
    load: #(
        'MongoDB Support'
        'In-Memory Tests'
    ).

Executing either script ensures all necessary classes and configurations required for document storage are available in the system.

External Data Dependencies

For the MongoDB backend to function, a running instance of the database server is required. This infrastructure setup involves installing the database engine and configuring network accessibility, details of which are generally handled by system administrators or deployment scripts outside the scope of this code-level documentation.