This trait wraps a String that is limited to a certain maximum length. Classes implementing this trait expose create and tryCreate methods to safely (and non-safely) construct such a String.

The canonical use case for LengthLimitedStrings is ensuring that we don't write too long strings into the database: Oracle has a length-limit of 1000 Unicode characters for the ordinary String type NVARCHAR2 and we are trying to avoid the use of CLOB (as it has pitfalls regarding implicits). This validation generally occurs on the server side and not on the client side. Concretely, this means that the Admin API and Ledger API gRPC services is the point where we validate that the received Protobuf Strings are not too long (and convert them into LengthLimitedStrings). On the client side, e.g. at the console, we generally take normal String types. The console command set_display_name and service com.digitalasset.canton.participant.admin.grpc.GrpcPartyNameManagementService validating request.displayName illustrate this.

As a rule of thumb: whenever you want to create a column that uses a NVARCHAR2 in Oracle, the value you write to it should use a LengthLimitedString.

Some more background on the Oracle issues: NVARCHAR and NVARCHAR2 have both by default a 4000 byte limit, but unicode uses 4-bytes per character (and nvarchar2 uses unicode) Therefore, NVARCHAR has a limit of 4000 and NVARCHAR2 has a limit of 1000 characters If need be, we can extend this to 32 KB by setting the Oracle database string size to 'extended mode' (ALTER SYSTEM SET MAX_STRING_SIZE=EXTENDED)

For longer strings, directly inherit from AbstractLengthLimitedString.