Hoist Core

https://github.com/xh/hoist-core
Admin
Hoist Core is the server-side implementation of a full-stack UI development framework for enterprise...
Tokens:216,366
Snippets:1,656
Trust Score:7.6
License:Apache-2.0
Update:6 days ago
Show doc for...
Tokens:
Raw
### list() and get() Examples

Source: https://github.com/xh/hoist-core/blob/develop/docs/gorm-domain-objects.md

Shows how to load all records, load by ID, and override fetch strategy at query time to avoid N+1 on associations.

```groovy
// Load all records
def allConfigs = AppConfig.list()

// Load by ID
def role = Role.get('HOIST_ADMIN')

// Override fetch strategy at query time (avoid N+1 on associations)
def portfolios = Portfolio.list(fetch: [positions: 'eager'])
```

--------------------------------

### Start the client with yarn start

Source: https://github.com/xh/hoist-core/blob/develop/docs/application-structure.md

Starts webpack-dev-server with hot module replacement. API requests are proxied to the Grails backend.

```bash
cd client-app && yarn start    # or: npm start
```

--------------------------------

### Customizing LogbackConfig

Source: https://github.com/xh/hoist-core/blob/develop/docs/logging.md

Shows how to create a subclass of LogbackConfig in the application's config directory to customize logging. The example calls super.configureLogging() to start with Hoist defaults, then raises a chatty package to ERROR and creates a dedicated monthly log for order tracking.

```groovy
// grails-app/init/com/myapp/MyAppLogbackConfig.groovy
package com.myapp

import io.xh.hoist.LogbackConfig
import static ch.qos.logback.classic.Level.*

class MyAppLogbackConfig extends LogbackConfig {

    protected void configureLogging() {
        // Start with the Hoist defaults
        super.configureLogging()

        // Raise a chatty package to ERROR
        logger('com.mycompany.chattylib', ERROR)

        // Create a dedicated monthly log for order tracking
        monthlyLog('order-tracking')
        logger('com.mycompany.orders', INFO, ['order-tracking'])
    }
}
```

--------------------------------

### Find CI JDK setup references

Source: https://github.com/xh/hoist-core/blob/develop/docs/upgrade-notes/v43-upgrade-notes.md

Search GitHub Actions workflows for java-version or Setup JDK steps to update them to match the new majorJavaVersion.

```bash
grep -rn "java-version\|Setup JDK" .github/workflows/
```

--------------------------------

### Example final gradle.properties

Source: https://github.com/xh/hoist-core/blob/develop/docs/upgrade-notes/v34-upgrade-notes.md

Example of a completed gradle.properties file after applying the upgrade steps. App-specific properties will vary.

```properties
xhAppCode=myapp
xhAppName=MyApp
xhAppPackage=com.example.myapp
xhAppVersion=X.Y-SNAPSHOT

grailsVersion=7.0.5
hoistCoreVersion=34.0.1
dotEnvGradlePluginVersion=4.0.0
hazelcast.version=5.6.0

runHoistInline=false
enableHotSwap=false
localDevXmx=2G

org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.jvmargs=-Dfile.encoding=UTF-8 -Xmx1024M
```

--------------------------------

### createIMap() example

Source: https://github.com/xh/hoist-core/blob/develop/docs/base-classes.md

Creates a Hazelcast IMap<K, V> for distributed partitioned data. The example creates an IMap named 'fileStore' for storing byte arrays.

```groovy
private IMap<String, byte[]> fileStore

void init() {
    fileStore = createIMap('fileStore')
}
```

--------------------------------

### Update CI JDK setup (before/after)

Source: https://github.com/xh/hoist-core/blob/develop/docs/upgrade-notes/v43-upgrade-notes.md

Update the Setup JDK step to use Java 21 (or '25' if majorJavaVersion=25). The after block shows the updated version.

```yaml
- name: Setup JDK 17
  uses: actions/setup-java@v5
  with:
      java-version: '17'
```

```yaml
- name: Setup JDK 21
  uses: actions/setup-java@v5
  with:
      java-version: '21'
```

--------------------------------

### YAML instance config example

Source: https://github.com/xh/hoist-core/blob/develop/docs/configuration.md

Example YAML file for instance configuration. Default location is /etc/hoist/conf/[appCode].yml, customizable via -Dio.xh.hoist.instanceConfigFile.

```yaml
dbHost: localhost
dbSchema: myapp
dbUser: myapp
dbPassword: secret
serverURL: http://localhost:8080/myapp
environment: Development
```

--------------------------------

### getTopic() publish example

Source: https://github.com/xh/hoist-core/blob/develop/docs/base-classes.md

Returns a Hazelcast ITopic<M> for publishing messages. The example publishes a map with action and source keys to the 'myCustomEvent' topic.

```groovy
getTopic('myCustomEvent').publish([action: 'refresh', source: username])
```

--------------------------------

### Constructor Pattern: Service with init()

Source: https://github.com/xh/hoist-core/blob/develop/docs/coding-conventions.md

Services should not declare constructors; use init() for setup. Declare types on injected dependencies. This example shows a PortfolioService with injected services and a cache created in init().

```groovy
class PortfolioService extends BaseService {

    ConfigService configService
    TrackService trackService

    private Cache<String, Portfolio> portfolioCache

    void init() {
        portfolioCache = createCache(name: 'portfolios', replicate: true)
    }
}
```

--------------------------------

### Start the Grails server with bootRun

Source: https://github.com/xh/hoist-core/blob/develop/docs/application-structure.md

Starts the Grails application on localhost:8080. The .env file provides instance configuration such as database credentials and environment.

```bash
./gradlew bootRun -Duser.timezone=Etc/UTC
```

--------------------------------

### .env.template example

Source: https://github.com/xh/hoist-core/blob/develop/docs/configuration.md

Example .env.template file showing required environment variables for a Hoist application. Copy to .env and customize. The bootstrap admin user is commented out for local dev only.

```bash
# .env.template — copy to .env and customize for your local environment.
# .env is gitignored and never committed.

# Required
APP_MYAPP_ENVIRONMENT=Development
APP_MYAPP_DB_HOST=localhost
APP_MYAPP_DB_SCHEMA=myapp
APP_MYAPP_DB_USER=myapp
APP_MYAPP_DB_PASSWORD=myapp
APP_MYAPP_SERVER_URL=http://localhost:8080/myapp

# Bootstrap admin — grants HOIST_ADMIN roles in local dev only
#APP_MYAPP_BOOTSTRAP_ADMIN_USER=dev.user
```

--------------------------------

### Source Files Table Example

Source: https://github.com/xh/hoist-core/blob/develop/docs/planning/docs-roadmap.md

Markdown table example showing how to list source files with their locations and roles. Use this early in each feature-area document.

```markdown
### Source Files

| File | Location | Role |
|------|----------|------|
| `ConfigService` | `grails-app/services/` | Primary service — typed getters, event publishing |
| `AppConfig` | `grails-app/domain/` | GORM domain class — database-backed config entries |
| `ConfigAdminController` | `grails-app/controllers/admin/` | Admin console CRUD endpoints |
```

--------------------------------

### Correct vs Incorrect Config Access Example

Source: https://github.com/xh/hoist-core/blob/develop/docs/planning/docs-roadmap.md

Groovy code example showing the correct use of a typed getter versus the incorrect raw access without type coercion. Use ✅/❌ markers for correct vs incorrect approaches.

```groovy
// ✅ Do: Use typed getter
String region = configService.getString('myAppRegion')

// ❌ Don't: Access raw value without type coercion
def region = configService.getObject('myAppRegion').value
```

--------------------------------

### HttpUtils Usage Examples

Source: https://github.com/xh/hoist-core/blob/develop/docs/http-client.md

Demonstrates how to set response cache headers and parse host/port strings using the HttpUtils utility class.

```groovy
import io.xh.hoist.http.HttpUtils

// Cache response for 15 minutes
HttpUtils.setResponseCache(response, 15)

// Disable caching
HttpUtils.setResponseCache(response, 0)

// Parse a host:port string from configuration
def (host, port) = HttpUtils.parseHostPort('api.example.com:8443')
// host = 'api.example.com', port = 8443

def (host2, port2) = HttpUtils.parseHostPort('api.example.com')
// host2 = 'api.example.com', port2 = null
```

--------------------------------

### Generated Project Structure

Source: https://github.com/xh/hoist-core/blob/develop/mcp/README.md

Shows the files generated by the install task: launchers under bin/ and the JAR under build/hoist-core-tools/lib/.

```text
<project>/
├── bin/
│   ├── .gitignore            # scoped ignore for the generated launchers (commit this)
│   ├── hoist-core-mcp        # invoked by .mcp.json (replaces start-hoist-core-mcp.sh)
│   ├── hoist-core-docs       # CLI: docs search/list/read/conventions/index/ping
│   ├── hoist-core-symbols    # CLI: symbols search/symbol/members
│   └── *.bat                 # Windows equivalents
└── build/hoist-core-tools/lib/
    └── hoist-core-mcp-<version>-all.jar
```

--------------------------------

### hoist-core-symbols: Search, get details, and list members

Source: https://github.com/xh/hoist-core/blob/develop/mcp/README.md

Commands for searching symbols by name, getting detailed type information, and listing all members of a class or interface. The first invocation in a process builds the Groovy AST index (~2-3s cold start).

```bash
# Search symbols by name (also searches indexed members of key framework classes)
hoist-core-symbols search BaseService
hoist-core-symbols search Cache --kind class
hoist-core-symbols search createTimer

# Get detailed type information for a symbol
hoist-core-symbols symbol BaseService
hoist-core-symbols symbol Cache --file src/main/groovy/io/xh/hoist/cache/Cache.groovy

# List all members of a class or interface
hoist-core-symbols members BaseService
hoist-core-symbols members Cache
```

--------------------------------

### parallelInit() Example in BootStrap.groovy

Source: https://github.com/xh/hoist-core/blob/develop/docs/base-classes.md

Shows how to call the static parallelInit() method from BootStrap.groovy to initialize groups of services in parallel. The caller decides the groups, not the services themselves.

```groovy
BaseService.parallelInit([configService, prefService])       // group 1
BaseService.parallelInit([portfolioService, marketService])  // group 2
```

--------------------------------

### RestController setup with restTarget and trackChanges

Source: https://github.com/xh/hoist-core/blob/develop/docs/base-classes.md

Point the controller at a GORM domain class and optionally enable audit tracking. The example sets restTarget to Position and trackChanges to true to log CRUD operations via TrackService.

```groovy
class PositionController extends RestController {
    static restTarget = Position       // GORM domain class to manage
    static trackChanges = true         // log CRUD operations via TrackService
}
```

--------------------------------

### Write from scratch

Source: https://github.com/xh/hoist-core/blob/develop/docs/monitoring.md

Full control approach. Build a service from BaseService with no dependency on the default. You are responsible for creating all Monitor rows and implementing all check methods.

```APIDOC
## Write from scratch

### Description
Full control approach. Build a service from BaseService with no dependency on the default. You are responsible for creating all Monitor rows and implementing all check methods.

### Method
N/A (Service implementation)

### Endpoint
N/A

### Parameters
#### Service Implementation
- **BaseService** - Required - The base class to extend.
- **Monitor rows** - Required - All Monitor rows must be created manually.
- **Check methods** - Required - All check methods must be implemented.

### Request Example
N/A

### Response
#### Success Response
- **Service implemented** - The service is fully custom and handles all monitor definitions and checks.

#### Response Example
N/A
```

--------------------------------

### Extend BaseService (Do) vs bare Grails service (Don't)

Source: https://github.com/xh/hoist-core/blob/develop/docs/coding-conventions.md

All Grails services must extend BaseService to get lifecycle, logging, identity, and admin stats. The 'Don't' example shows a bare Grails service that misses these features.

```groovy
// Do
class PortfolioService extends BaseService {
    ...
}

// Don't: bare Grails service misses lifecycle, logging, identity, admin stats
class PortfolioService {
    ...
}
```

--------------------------------

### Use managed resource factories (Do) vs raw Hazelcast/Spring (Don't)

Source: https://github.com/xh/hoist-core/blob/develop/docs/coding-conventions.md

Create caches, timers, and Hazelcast structures via BaseService factory methods to get naming, ClusterService registration, lifecycle cleanup, and admin visibility. The 'Don't' example shows raw Hazelcast and Spring scheduling that bypasses lifecycle and registry.

```groovy
// Do: managed factories
class PortfolioService extends BaseService {

    private Cache<String, Portfolio> portfolioCache
    private Timer refreshTimer

    void init() {
        portfolioCache = createCache(name: 'portfolios', expireTime: 10 * MINUTES, replicate: true)
        refreshTimer = createTimer(name: 'refreshTimer', interval: 60 * SECONDS, runFn: this.&refresh, primaryOnly: true)
    }
}

// Don't: raw Hazelcast / raw Spring scheduling — bypasses lifecycle and registry
class PortfolioService extends BaseService {
    private IMap<String, Portfolio> map = Hazelcast.getMap('portfolios')
    private ScheduledExecutorService exec = Executors.newScheduledThreadPool(1)
}
```

--------------------------------

### Recompile with Gradle

Source: https://github.com/xh/hoist-core/blob/develop/docs/upgrade-notes/v40-upgrade-notes.md

Run this Gradle command to recompile the project after applying the v40 upgrade changes. Expect possible compile failures related to pre-built Timer/Counter usage or 3-positional span calls.

```bash
./gradlew compileGroovy
```

--------------------------------

### Making a Simple GET Request

Source: https://github.com/xh/hoist-core/blob/develop/docs/http-client.md

Executes a basic GET request and parses the response as a map.

```groovy
def client = new JSONClient()
def result = client.executeAsMap(new HttpGet('https://api.example.com/users/42'))
String name = result.name
```

--------------------------------

### setValue usage examples

Source: https://github.com/xh/hoist-core/blob/develop/docs/configuration.md

Examples of calling setValue with different value types and an explicit lastUpdatedBy.

```groovy
configService.setValue('maxRetries', 5)
configService.setValue('dashboardSettings', [theme: 'dark', layout: 'grid'])
configService.setValue('apiEndpoint', 'https://new-api.example.com', 'batch-job')
```

--------------------------------

### Typical Entry Point app.ts

Source: https://github.com/xh/hoist-core/blob/develop/docs/application-structure.md

Calls XH.renderApp() with the app's root component, model, and authentication configuration.

```typescript
import '../Bootstrap';
import {XH} from '@xh/hoist/core';
import {AppContainer} from '@xh/hoist/desktop/appcontainer';
import {AppComponent} from '../app/AppComponent';
import {AppModel} from '../app/AppModel';

XH.renderApp({
    clientAppCode: 'app',
    componentClass: AppComponent,
    modelClass: AppModel,
    containerClass: AppContainer,
    isMobileApp: false,
    enableLogout: true,
    checkAccess: 'APP_READER'
});
```

--------------------------------

### Advisory sub-bullet example

Source: https://github.com/xh/hoist-core/blob/develop/docs/changelog-format.md

Example of how to write an advisory warning using STE, avoiding ambiguous modals like 'should'.

```markdown
* ⚠️ An app that bootstraps a typed config with `typedClass` now gets a WARN at startup unless it
  declares `defaultValue: [:]` in the `ConfigSpec`.
```

--------------------------------

### Install Hoist Core Tools via Gradle

Source: https://github.com/xh/hoist-core/blob/develop/mcp/README.md

Run this command once after adding the snippet and again after a version bump to generate project-local launchers under <project>/bin/.

```bash
./gradlew installHoistCoreTools
```

--------------------------------

### hoist-core-docs: Search, list, read, and ping documentation

Source: https://github.com/xh/hoist-core/blob/develop/mcp/README.md

Commands for searching documentation by keyword, listing available documents, reading specific documents, using shortcuts for common documents, and running a sanity check. Use --help for full usage.

```bash
# Search documentation by keyword
hoist-core-docs search "BaseService lifecycle"
hoist-core-docs search "authentication" --category concept
hoist-core-docs search "Cache" -l 5

# List all available documents
hoist-core-docs list
hoist-core-docs list --category package

# Read a specific document by id
hoist-core-docs read docs/base-classes.md
hoist-core-docs read docs/coding-conventions.md

# Shortcuts for common documents
hoist-core-docs conventions     # docs/coding-conventions.md
hoist-core-docs index           # docs/README.md

# Sanity check
hoist-core-docs ping
```

--------------------------------

### Before: javax.servlet imports

Source: https://github.com/xh/hoist-core/blob/develop/docs/upgrade-notes/v34-upgrade-notes.md

Shows the old javax.servlet imports that need to be replaced with jakarta.servlet equivalents.

```groovy
import javax.servlet.http.HttpServletRequest
import javax.servlet.http.HttpServletResponse
```

--------------------------------

### createCachedValue() example

Source: https://github.com/xh/hoist-core/blob/develop/docs/base-classes.md

Creates a CachedValue<V> with replication and expiry options. The example shows a summary map cached for 30 minutes and replicated across the cluster.

```groovy
private CachedValue<Map> summary

void init() {
    summary = createCachedValue(name: 'summary', replicate: true, expireTime: 30 * MINUTES)
}
```

--------------------------------

### After: ConfigSpec with defaultValue: AppConfig.NONE

Source: https://github.com/xh/hoist-core/blob/develop/docs/upgrade-notes/v41-upgrade-notes.md

New way using AppConfig.NONE constant. Requires import io.xh.hoist.config.AppConfig.

```groovy
new ConfigSpec(
    name: 'myApiKey',
    valueType: 'pwd',
    defaultValue: AppConfig.NONE,
    groupName: 'MyApp'
)
```

--------------------------------

### createTimer() example

Source: https://github.com/xh/hoist-core/blob/develop/docs/base-classes.md

Creates a managed Timer that runs a closure on an interval. The example configures a timer to call refreshData every 5 minutes, with primaryOnly, delay, and timeout options.

```groovy
void init() {
    createTimer(
        name: 'refreshData',
        runFn: this.&refreshData,
        interval: 5 * MINUTES,
        primaryOnly: true,            // only run on the primary instance
        delay: true,                  // wait one interval before first run
        timeout: 3 * MINUTES          // max execution time (cancels task and logs error on timeout)
    )
}

private void refreshData() {
    // Called periodically by the timer
}
```

--------------------------------

### After: hoist-core MCP install snippet v2

Source: https://github.com/xh/hoist-core/blob/develop/docs/upgrade-notes/v43-upgrade-notes.md

The v2 snippet for installing hoist-core MCP tools. It uses configurations.hoistCoreCli.withDependencies to resolve the dependency, avoiding the configuration-time resolution that fails under Grails 8.

```groovy
// hoist-ai-snippet: hoist-core-install/v2 -- DO NOT REMOVE (drift marker, see hoist-core/mcp/README.md)
configurations {
    hoistCoreCli
}

configurations.hoistCoreCli.withDependencies { deps ->
    def hc = configurations.runtimeClasspath.incoming.resolutionResult.allComponents
        .find { it.moduleVersion?.group == 'io.xh' && it.moduleVersion?.name == 'hoist-core' }
    if (!hc) throw new GradleException(
        'hoist-core not found on the runtimeClasspath -- cannot install hoist-core tools.')
    deps.add(project.dependencies.create("io.xh:hoist-core-mcp:${hc.moduleVersion.version}:all@jar"))
}
```

--------------------------------

### createCache() Example

Source: https://github.com/xh/hoist-core/blob/develop/docs/base-classes.md

Demonstrates using the createCache() factory method to create a managed cache with a name, expiry time, and replication flag. Resource names must be unique within a service.

```groovy
private Cache<String, List<Position>> positionCache

void init() {
    positionCache = createCache(name: 'positions', expireTime: 5 * MINUTES, replicate: true)
}
```

--------------------------------

### Controlling stacktraces and start messages

Source: https://github.com/xh/hoist-core/blob/develop/docs/logging.md

Shows how to suppress stacktraces for a noisy logger via a LogLevel entry in the admin console. Also notes that start messages for withInfo/withDebug/withTrace are off by default and can be enabled with includeStartMessages.

```groovy
// In the admin console Log Levels tab:
// Set io.xh.hoist.mypackage.NoisyService -> suppressStackTrace = true
//
// Now logError/logWarn calls on NoisyService will omit stacktraces.
// Set a more-specific entry to False to override for a specific subclass.
```

--------------------------------

### After: Reading config with getPwdIfSet

Source: https://github.com/xh/hoist-core/blob/develop/docs/upgrade-notes/v41-upgrade-notes.md

New pattern using getPwdIfSet to avoid the 'none' comparison.

```groovy
String apiKey = configService.getPwdIfSet('myApiKey')
if (!apiKey) throw new RuntimeException('myApiKey not configured')
```

--------------------------------

### Before: hoist-core MCP install snippet v1

Source: https://github.com/xh/hoist-core/blob/develop/docs/upgrade-notes/v43-upgrade-notes.md

The v1 snippet for installing hoist-core MCP tools. It resolves runtimeClasspath during configuration, which fails under the Grails 8 Gradle plugin. Replace it with the v2 version.

```groovy
// hoist-ai-snippet: hoist-core-install/v1 -- DO NOT REMOVE (drift marker, see hoist-core/mcp/README.md)
configurations {
    hoistCoreCli
}

dependencies {
    hoistCoreCli providers.provider {
        def hc = configurations.runtimeClasspath.incoming.resolutionResult.allComponents
            .find { it.moduleVersion?.group == 'io.xh' && it.moduleVersion?.name == 'hoist-core' }
        if (!hc) throw new GradleException(
            'hoist-core not found on the runtimeClasspath -- cannot install hoist-core tools.')
        "io.xh:hoist-core-mcp:${hc.moduleVersion.version}:all@jar"
    }
}
```

--------------------------------

### Timed execution block with withInfo

Source: https://github.com/xh/hoist-core/blob/develop/docs/logging.md

Demonstrates using withInfo to log a message when a block starts and completes, including elapsed time. The output shows the completion message with duration. An optional 'started' message appears when includeStartMessages is enabled on the LogLevel entry.

```groovy
class DataSyncService extends BaseService {

    void syncAll() {
        withInfo('Syncing external data') {
            fetchRemoteRecords()
            updateLocalDatabase()
        }
    }
}
```

```text
14:32:05.500 | inst1 | DataSyncService [INFO] | jdoe | Syncing external data | completed | 2340ms
```

```text
14:32:05.500 | inst1 | DataSyncService [INFO] | jdoe | Syncing external data | started
14:32:07.840 | inst1 | DataSyncService [INFO] | jdoe | Syncing external data | completed | 2340ms
```

--------------------------------

### Basic logging in a service (logInfo, logDebug)

Source: https://github.com/xh/hoist-core/blob/develop/docs/logging.md

Shows how to log info and debug messages in a service class extending BaseService. The logInfo call includes a message and a map of key-value pairs, while logDebug passes a single value. Output shows the log format with timestamp, instance, class, level, user, and message.

```groovy
class OrderService extends BaseService {

    void processOrder(Map order) {
        logInfo('Processing order', [orderId: order.id, customer: order.customer])
        // ...
        logDebug('Validated order details', order.id)
    }
}
```

```text
14:32:01.123 | inst1 | OrderService [INFO] | jdoe | Processing order | orderId=ORD-123 | customer=Acme Corp
14:32:01.130 | inst1 | OrderService [DEBUG] | jdoe | Validated order details | ORD-123
```
Tokens:
Raw