Global Objects#

Adama has several built-in global objects that give documents access to platform services, time, randomness, messaging, and identity operations. They're always available -- no imports needed.

Time#

The Time global handles temporal values and timezone management. Every document has its own timezone (defaults to "UTC") that affects how dates and times get computed.

Getting Current Values#

public long timestamp;
public date today;
public datetime now;
public time current_time;

@construct {
  timestamp = Time.now();
  today = Time.today();
  now = Time.datetime();
  current_time = Time.time();
}

Timezone Management#

Every document starts in "UTC". Changing the timezone affects how Time.today(), Time.datetime(), and Time.time() compute their values.

public string tz;
public bool zone_set;

@construct {
  tz = Time.zone();                            // "UTC"
  zone_set = Time.setZone("America/New_York"); // true
  tz = Time.zone();                            // "America/New_York"
}

Time.setZone() validates the timezone string against Java's IANA time zone database. Returns true on success, false if the timezone is garbage.

Valid timezone formats:

• IANA identifiers: "America/New_York", "Europe/London", "Asia/Tokyo", "Australia/Sydney"
• UTC offsets: "UTC", "UTC+5:30", "UTC-8"

public bool ok1;
public bool ok2;
public bool bad;

@construct {
  ok1 = Time.setZone("Europe/London");   // true
  ok2 = Time.setZone("Asia/Tokyo");      // true
  bad = Time.setZone("Not/A/Zone");      // false - timezone unchanged
}

Timezone Effects on DateTime#

When you change the timezone, all subsequent calls to Time.today(), Time.datetime(), and Time.time() reflect the new timezone:

public datetime dt_utc;
public datetime dt_eastern;

#capture_utc {
  dt_utc = Time.datetime();           // e.g. 2025-01-15T20:00:00Z[UTC]
  Time.setZone("America/New_York");
}

#capture_eastern {
  dt_eastern = Time.datetime();       // e.g. 2025-01-15T15:00:00-05:00[America/New_York]
}

Time Utility Functions#

These operate on time values and are inherited from the LibTime parent:

maybe<time> t = Time.make(14, 30);  // 2:30 PM
time evening = @time 23:00;
time extended = Time.extendWithinDay(evening, @timespan 2 hr);  // clamped
time wrapped = Time.cyclicAdd(evening, @timespan 2 hr);          // wraps to 01:00

bool conflict = Time.overlaps(@time 9:00, @time 10:30, @time 10:00, @time 11:00);  // true

Document#

The Document global gives you access to the document's identity and lifecycle operations.

Document Identity#

public string doc_key;
public string doc_space;
public int doc_seq;

@construct {
  doc_key = Document.key();
  doc_space = Document.space();
  doc_seq = Document.seq();
}

Document Lifecycle#

// Force a principal to disconnect
procedure kick_user(principal who) {
  Document.disconnect(who);
}

// Apply a dynamic patch
message PatchRequest {
  dynamic data;
}

channel apply_patch(PatchRequest req) {
  Document.patch(req.data);
}

Random#

The Random global gives you deterministic pseudo-random number generation. The random state is part of the document state, which means it's reproducible during replay -- important for maintaining consistency.

// Dice roll (1-6)
int roll = Random.genBoundInt(6) + 1;

// Coin flip
bool heads = Random.genDouble() < 0.5;

// Shuffle a table
record Card {
  public int id;
  public int ordering;
}
table<Card> deck;

procedure shuffle() {
  (iterate deck).ordering = Random.genInt();
}

Principal#

The Principal global handles identity creation and inspection.

Creating Principals#

principal p = Principal.principalOf("user123");
// Equivalent extension method:
principal p2 = "user123".principalOf();

Inspecting Principals#

principal p = Principal.principalOf("admin");

string agent = Principal.agent(p);           // "admin"
string auth = Principal.authority(p);        // "doc/space/key"
bool is_doc = Principal.isFromDocument(p);   // true
bool is_space = Principal.isFromSpace(p);    // true
bool is_anon = Principal.isAnonymous(p);     // false

// Extension method style
bool from_adama = p.fromAuthority("adama");

ViewState#

The ViewState global lets you manipulate client view state from the server side during message handling. These functions only do something meaningful inside channel handlers where there's an active client connection.

channel submit(SubmitMsg msg) {
  // Update the client's view state
  ViewState.merge(@dynamic {"status": "processing"});

  // Navigate client to results page
  ViewState.goto("results");

  // Send notification to client
  ViewState.send("notification", @dynamic {"message": "Done!"});

  // Log for debugging
  ViewState.log("submission processed");
}

Messaging#

The Messaging global lets you send messages programmatically within a document.

public int event_count;

message Event {
  int value;
}

channel on_event(Event e) {
  event_count += e.value;
}

procedure trigger_event() {
  Messaging.send("on_event", @dynamic {"value": 1});
}

procedure notify_all() {
  Messaging.broadcast("on_event", @dynamic {"value": 0});
}

Method Summary#

Time#

Document#

Random#

Principal#