Slice Metadata Directives

Overview

Slice has the concept of a metadata directive. For example:

["java:type:java.util.LinkedList<Integer>"] sequence<int> IntSeq;

A metadata directive can appear as a prefix to any Slice definition. Metadata directives appear in a pair of square brackets and contain one or more string literals separated by commas. For example, the following is a syntactically valid metadata directive containing two strings:

["a", "b"] interface Example {}

Metadata directives are not part of the Slice language per se: the presence of a metadata directive has no effect on the client-server contract, that is, metadata directives do not change the Slice type system in any way. Instead, metadata directives are targeted at specific back-ends, such as the code generator for a particular language mapping. In the preceding example, the java: prefix indicates that the directive is targeted at the Slice to Java compiler.

Metadata directives permit you to provide supplementary information that does not change the Slice types being defined, but somehow influences how the compiler will generate code for these definitions. For example, a metadata directive java:type:java.util.LinkedList<T> instructs the Slice to Java compiler to map a sequence to a linked list instead of an array (which is the default).

Metadata directives are also used to create skeletons that support Asynchronous Method Dispatch (AMD) in some languages.

Apart from metadata directives that are attached to a specific definition, there are also file metadata directives. For example:

[["cpp:dll-export:WIDGET_API"]]

Note that a file metadata directive is enclosed by double square brackets, whereas a local metadata directive (one that is attached to a specific definition) is enclosed by single square brackets. File metadata directives are used to pass instructions that affect the entire Slice file. File metadata directives must precede any definitions in a file (but can appear following any #include directives).

We describe below the metadata directives you can use.

General Metadata Directives

amd

This directive applies to interfaces and operations.

In C++, C#, and Java, this directive instructs the Slice compiler to generate an asynchronous method in the skeleton class or interface instead of the default synchronous method. You could alternatively make your servant class derive from an async skeleton, and not rely on this metadata directive. See Operations for details.

This directive is ignored by other Slice compilers.

deprecated[:message]
deprecate[:message]

This directive allows you to emit a deprecation warning for Slice constructs.

format

This directive defines the encoding format used for any classes or exceptions marshaled as the arguments or results of an operation. The tag can be applied to an interface, which affects all of its operations, or to individual operations. Legal values for the tag are format:sliced, format:compact, and format:default. A tag specified for an operation overrides any setting applied to its enclosing interface. The Ice.Default.SlicedFormat property defines the behavior when no tag is present.

marshaled-result

This directive applies to operations and changes the return type of mapped skeleton methods in C++, C#, and Java. It has no effect on the client-side mapping.

With this directive, the mapped skeleton method returns a “marshaled result” struct or class that marshals the return value and out parameters immediately in its constructor. This allows you to perform the marshaling in a thread-safe manner, typically while holding a mutex lock.

For example:

sequence<int> IntSeq;
sequence<IntSeq> IntIntSeq;
sequence<string> StringSeq;

class Grid
{
    StringSeq xLabels;
    StringSeq yLabels;
    IntIntSeq values;
}
  
interface GridIntf
{
   // We want to marshal the returned Grid object within a lock,
   // and return a consistent object not affected by concurrent calls to
   // clearValues.
   ["marshaled-result"] 
   ["cs:identifier:GetGrid"]
   Grid getGrid();
   
   void clearValues();
}

The mapped skeleton method for getGrid is:

GridIntf_GetGridMarshaledResult GetGrid(Ice.Current current);

where GridnIntf_GetGridMarshaledResult is a generated record struct with a constructor that accepts a parameter for the return value, followed by Current:

// Generated server-side code
public readonly record struct GridIntf_GetGridMarshaledResult : Ice.MarshaledResult
{
    // Marshals returnValue immediately.
    public GridIntf_GetGridMarshaledResult(Grid? ret, Ice.Current current)
    {
        ...
    }
    ...
}

A typical implementation of the getGridoperation in your servant would be:

public override GridIntf_GetGridMarshaledResult GetGrid(Ice.Current current)
{
    lock (_mutex)
    {
       // marshal _grid field within synchronization
       return new GridIntf_GetGridMarshaledResult(_grid, current); 
    }
}

The mapped skeleton method for getGrid is:

GridIntf.GetGridMarshaledResult getGrid(com.zeroc.Ice.Current current);

where GetGridMarshaledResult is a nested static class with a constructor that accepts a parameter for the return value, followed by Current:

// Generated server-side code
public interface GridIntf extends com.zeroc.Ice.Object {
    public static class GetGridMarshaledResult implements 
          com.zeroc.Ice.MarshaledResult {
        public GetGridMarshaledResult(
            Grid returnValue, 
            com.zeroc.Ice.Current current) {
            ...
        }
    }
    ...
}

A typical implementation of the getGridoperation in your servant would be:

@Override 
public GridIntf.GetGridMarshaledResult getGrid(com.zeroc.Ice.Current current) {
    synchronized (_mutex) {
       // marshal _grid field within synchronization
       return new GridIntf.GetGridMarshaledResult(_grid, current); 
    }
}

A marshaled-result instance is specific to a request. Do not cache a marshaled result and return it for another request.

suppress-warning

This file directive allows to suppress Slice compiler warnings. It applies to all definitions in the Slice file that includes this directive. If one or more categories are specified (for example "suppress-warning:invalid-metadata" or "suppress-warning:deprecated, invalid-metadata") only warnings matching these categories will be suppressed, otherwise all warnings are suppressed. The categories are described in the following table:

Language-Specific Metadata Directives

The metadata directives for C# uses the cs prefix.

cs:attribute

This directive applies to enums, enumerators, constants and fields. It injects a C# attribute definition into the generated code.

cs:class

This directive applies to Slice structures. It directs the Slice compiler to emit a C# class instead of a structure.

cs:generic:List, cs:generic:LinkedList, cs:generic:Queue and cs:generic:Stack

These directives apply to sequences and map them to the specified sequence type.

cs:generic:SortedDictionaryand cs:generic:SortedList

This directive applies to dictionaries and maps them to the specified type.

cs:generic:csharp-custom-type

This directive applies to sequences and allows you map them to custom types.

cs:identifier:csharp-identifier

This directive applies to all Slice constructs, and instructs the Slice compiler to use the specified csharp-identifier.

For example:

interface Greeter
{
    ["cs:identifier:Greet"]
    string greet(string name);
}

The cs:identifierdirective in this example ensures operation greet is mapped to methods Greet and GreetAsync in C#, instead of the default (greet and greetAsync).

cs:namespace:enclosing-csharp-namespace

This deprecated directive applies to top-level modules. It instructs the Slice compiler to place the generated C# namespace in the specified namespace. You should use cs:identifier instead.

cs:property

This directive applies to Slice structures, classes, and exceptions. It directs the Slice compiler to map Slice fields to C# properties instead of C# fields.