Package io.pravega.schemaregistry.client

Interface SchemaRegistryClient

  • All Superinterfaces:
    java.lang.AutoCloseable
    All Known Implementing Classes:
    SchemaRegistryClientImpl
    @Beta
public interface SchemaRegistryClient
extends java.lang.AutoCloseable
    Defines a registry client for interacting with schema registry service. The implementation of this interface should provide read-after-write-consistency guarantees for all the methods.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addCodecType​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.CodecType codecType)
      Add new codec type to be used in encoding in the group.
      boolean addGroup​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.GroupProperties groupProperties)
      Adds a new group.
      io.pravega.schemaregistry.contract.data.VersionInfo addSchema​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.SchemaInfo schemaInfo)
      Registers schema to the group.
      boolean canReadUsing​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.SchemaInfo schemaInfo)
      Checks whether given schema can be used to read by validating it for reads against one or more existing schemas in the group subject to current GroupProperties.getCompatibility() policy.
      void deleteSchemaVersion​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.VersionInfo versionInfo)
      Deletes the schema associated to the given version.
      java.util.List<io.pravega.schemaregistry.contract.data.CodecType> getCodecTypes​(java.lang.String groupId)
      List of codec types used for encoding in the group.
      io.pravega.schemaregistry.contract.data.EncodingId getEncodingId​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.VersionInfo versionInfo, java.lang.String codecType)
      Gets an encoding id that uniquely identifies a combination of Schema version and codec type.
      io.pravega.schemaregistry.contract.data.EncodingInfo getEncodingInfo​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.EncodingId encodingId)
      Gets encoding info against the requested encoding Id.
      java.util.List<io.pravega.schemaregistry.contract.data.GroupHistoryRecord> getGroupHistory​(java.lang.String groupId)
      Gets complete schema evolution history of the group with schemas, versions, compatibility policy and time when the schema was added to the group.
      io.pravega.schemaregistry.contract.data.GroupProperties getGroupProperties​(java.lang.String groupId)
      Get group properties for the group identified by the group id.
      io.pravega.schemaregistry.contract.data.SchemaWithVersion getLatestSchemaVersion​(java.lang.String groupId, java.lang.String schemaType)
      Gets latest schema and version for the group (or type, if specified).
      java.lang.String getNamespace()
      The Namespace which is used for making all client requests to registry service.
      io.pravega.schemaregistry.contract.data.SchemaInfo getSchemaForVersion​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.VersionInfo versionInfo)
      Gets schema corresponding to the version.
      java.util.Map<java.lang.String,​io.pravega.schemaregistry.contract.data.VersionInfo> getSchemaReferences​(io.pravega.schemaregistry.contract.data.SchemaInfo schemaInfo)
      Finds all groups and corresponding version info for the groups where the supplied schema has been registered.
      java.util.List<io.pravega.schemaregistry.contract.data.SchemaWithVersion> getSchemas​(java.lang.String groupId)
      Gets list of latest schemas for each object types registered under the group.
      java.util.List<io.pravega.schemaregistry.contract.data.SchemaWithVersion> getSchemaVersions​(java.lang.String groupId, java.lang.String schemaType)
      Gets all schemas with corresponding versions for the group (or type, if specified).
      io.pravega.schemaregistry.contract.data.VersionInfo getVersionForSchema​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.SchemaInfo schemaInfo)
      Gets version corresponding to the schema.
      java.util.Iterator<java.util.Map.Entry<java.lang.String,​io.pravega.schemaregistry.contract.data.GroupProperties>> listGroups()
      List all groups that the user is authorized on.
      void removeGroup​(java.lang.String groupId)
      Removes a group identified by the groupId.
      boolean updateCompatibility​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.Compatibility compatibility, io.pravega.schemaregistry.contract.data.Compatibility previous)
      Update group's schema validation policy.
      boolean validateSchema​(java.lang.String groupId, io.pravega.schemaregistry.contract.data.SchemaInfo schemaInfo)
      Checks whether given schema is valid by applying compatibility policy against previous schemas in the group subject to current GroupProperties.getCompatibility() policy.

      • Methods inherited from interface java.lang.AutoCloseable

        close

    • Method Detail

      • addGroup

        boolean addGroup​(java.lang.String groupId,
                 io.pravega.schemaregistry.contract.data.GroupProperties groupProperties)
          throws RegistryExceptions.BadArgumentException,
                 RegistryExceptions.UnauthorizedException
        Adds a new group. A group refers to the name under which the schemas are registered. A group is identified by a unique id and has an associated set of group metadata GroupProperties and a list of codec types and a versioned history of schemas that were registered under the group. Add group is idempotent. If the group by the same id already exists the api will return false.
        Parameters:
        groupId - Id for the group that uniquely identifies the group.
        groupProperties - groupProperties Group properties for the group. These include serialization format, compatibility policy, and flag to declare whether multiple schemas representing distinct object types can be registered with the group. Type identify objects of same type. Schema compatibility checks are always performed for schemas that share same SchemaInfo.getType(). Additionally, a user defined map of properties can be supplied.
        Returns:
        True indicates if the group was added successfully, false if it exists.
        Throws:
        RegistryExceptions.BadArgumentException - if the group properties is rejected by service.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • removeGroup

        void removeGroup​(java.lang.String groupId)
          throws RegistryExceptions.UnauthorizedException
        Removes a group identified by the groupId. This will remove all the codec types and schemas registered under the group. Remove group is idempotent.
        Parameters:
        groupId - Id for the group that uniquely identifies the group.
        Throws:
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • listGroups

        java.util.Iterator<java.util.Map.Entry<java.lang.String,​io.pravega.schemaregistry.contract.data.GroupProperties>> listGroups()
                                                                                                                            throws RegistryExceptions.UnauthorizedException
        List all groups that the user is authorized on. This returns an iterator where each element is a pair of group name and group properties. The list group is a non atomic call. The implementation is not necessarily consistent as it uses paginated iteration using Continuation Token. This could mean that as the list is being iterated over, the state on the server may be updated (some groups added or removed). For example, if a group that has been iterated over is deleted and recereated, the iterator may deliver a group with identical name twice. Similarly, If a group that has not yet been iterated over is deleted, the client may or may not see the group as it is iterating over the response depending on whether the client had received the deleted group from service before it was deleted or not. This iterator can be used to iterate over each element until all elements are exhausted and gives a weak guarantee that all groups added before the iterator Iterator.hasNext() = false can be iterated over.
        Returns:
        map of names of groups with corresponding group properties for all groups.
        Throws:
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • getGroupProperties

        io.pravega.schemaregistry.contract.data.GroupProperties getGroupProperties​(java.lang.String groupId)
                                                                    throws RegistryExceptions.ResourceNotFoundException,
                                                                           RegistryExceptions.UnauthorizedException
        Get group properties for the group identified by the group id. GroupProperties.serializationFormat which identifies the serialization format is used to describe the schema. GroupProperties.getCompatibility() sets the schema validation policy that needs to be enforced for evolving schemas. GroupProperties.isAllowMultipleTypes() that specifies if multiple schemas are allowed to be registered in the group. Schemas are validated against existing schema versions that have the same SchemaInfo.getType(). GroupProperties.properties describes generic properties for a group.
        Parameters:
        groupId - Id for the group.
        Returns:
        Group properties which includes property like Serialization format and compatibility policy.
        Throws:
        RegistryExceptions.ResourceNotFoundException - if group is not found.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • updateCompatibility

        boolean updateCompatibility​(java.lang.String groupId,
                            io.pravega.schemaregistry.contract.data.Compatibility compatibility,
                            @Nullable
                            io.pravega.schemaregistry.contract.data.Compatibility previous)
                     throws RegistryExceptions.ResourceNotFoundException,
                            RegistryExceptions.UnauthorizedException
        Update group's schema validation policy. If previous compatibility policy are not supplied, then the update to the policy will be performed unconditionally. However, if previous compatibility policy are supplied, then the update will be performed if and only if existing GroupProperties.getCompatibility() match previous compatibility policy.
        Parameters:
        groupId - Id for the group.
        compatibility - New Compatibility for the group.
        previous - Previous compatibility.
        Returns:
        true if the update was accepted by the service, false if it was rejected because of precondition failure. Precondition failure can occur if previous compatibility policy were specified and they do not match the policy set on the group.
        Throws:
        RegistryExceptions.ResourceNotFoundException - if group is not found.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • getSchemas

        java.util.List<io.pravega.schemaregistry.contract.data.SchemaWithVersion> getSchemas​(java.lang.String groupId)
                                                                              throws RegistryExceptions.ResourceNotFoundException,
                                                                                     RegistryExceptions.UnauthorizedException
        Gets list of latest schemas for each object types registered under the group. Objects are identified by SchemaInfo.getType(). Schema registry provides consistency guarantees. So all schemas added before this call will be returned by this call. However, the service side implementation is not guaranteed to be atomic. So if schemas are being added concurrently, the schemas returned by this api may or may not include those.
        Parameters:
        groupId - Id for the group.
        Returns:
        Unordered list of different objects within the group.
        Throws:
        RegistryExceptions.ResourceNotFoundException - if group is not found.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • getEncodingInfo

        io.pravega.schemaregistry.contract.data.EncodingInfo getEncodingInfo​(java.lang.String groupId,
                                                                     io.pravega.schemaregistry.contract.data.EncodingId encodingId)
                                                              throws RegistryExceptions.ResourceNotFoundException,
                                                                     RegistryExceptions.UnauthorizedException
        Gets encoding info against the requested encoding Id. The purpose of encoding info is to uniquely identify the encoding used on the data at rest. The encoding covers two parts - 1. Schema that defines the structure of the data and is used for serialization. A specific schema version registered with registry service is uniquely identified by the corresponding VersionInfo object. 2. CodecType that is used to encode the serialized data. This would typically be some compression. The codecType and schema should both be registered with the service and service will generate a unique identifier for each such pair. Encoding Info uniquely identifies a combination of a versionInfo and codecType. EncodingInfo also includes the SchemaInfo identified by the VersionInfo.
        Parameters:
        groupId - Id for the group.
        encodingId - Encoding id that uniquely identifies a schema within a group.
        Returns:
        Encoding info corresponding to the encoding id.
        Throws:
        RegistryExceptions.ResourceNotFoundException - if group or encoding id is not found.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • getLatestSchemaVersion

        io.pravega.schemaregistry.contract.data.SchemaWithVersion getLatestSchemaVersion​(java.lang.String groupId,
                                                                                 @Nullable
                                                                                 java.lang.String schemaType)
                                                                          throws RegistryExceptions.ResourceNotFoundException,
                                                                                 RegistryExceptions.UnauthorizedException
        Gets latest schema and version for the group (or type, if specified). To get latest schema version for a specific type identified by SchemaInfo.getType(), provide the type. Otherwise if the group is configured to allow multiple schemas GroupProperties.isAllowMultipleTypes(), then and type is not specified, then last schema added to the group across all types will be returned.
        Parameters:
        groupId - Id for the group.
        schemaType - Type of object identified by SchemaInfo.getType().
        Returns:
        Schema with version for the last schema that was added to the group (or type).
        Throws:
        RegistryExceptions.ResourceNotFoundException - if group is not found.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • getSchemaVersions

        java.util.List<io.pravega.schemaregistry.contract.data.SchemaWithVersion> getSchemaVersions​(java.lang.String groupId,
                                                                                            @Nullable
                                                                                            java.lang.String schemaType)
                                                                                     throws RegistryExceptions.ResourceNotFoundException,
                                                                                            RegistryExceptions.UnauthorizedException
        Gets all schemas with corresponding versions for the group (or type, if specified). For groups configured with GroupProperties.isAllowMultipleTypes(), the type SchemaInfo.getType() should be supplied to view schemas specific to a type. if type is null, all schemas in the group are returned. The order in the list matches the order in which schemas were evolved within the group.
        Parameters:
        groupId - Id for the group.
        schemaType - type of object identified by SchemaInfo.getType().
        Returns:
        Ordered list of schemas with versions and compatibility policy for all schemas in the group.
        Throws:
        RegistryExceptions.ResourceNotFoundException - if group is not found.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • validateSchema

        boolean validateSchema​(java.lang.String groupId,
                       io.pravega.schemaregistry.contract.data.SchemaInfo schemaInfo)
                throws RegistryExceptions.ResourceNotFoundException,
                       RegistryExceptions.UnauthorizedException
        Checks whether given schema is valid by applying compatibility policy against previous schemas in the group subject to current GroupProperties.getCompatibility() policy. The invocation of this method will perform exactly the same validations as addSchema(String, SchemaInfo) but without registering the schema. This is primarily intended to be used during schema development phase to validate that the changes to schema are in compliance with compatibility policy for the group.
        Parameters:
        groupId - Id for the group.
        schemaInfo - Schema to check for validity.
        Returns:
        A schema is valid if it passes all the GroupProperties.getCompatibility(). The rule supported are allow any, deny all or a combination of BackwardAndForward. If desired compatibility is satisfied by the schema then this method returns true, false otherwise.
        Throws:
        RegistryExceptions.ResourceNotFoundException - if group is not found.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • getGroupHistory

        java.util.List<io.pravega.schemaregistry.contract.data.GroupHistoryRecord> getGroupHistory​(java.lang.String groupId)
                                                                                    throws RegistryExceptions.ResourceNotFoundException,
                                                                                           RegistryExceptions.UnauthorizedException
        Gets complete schema evolution history of the group with schemas, versions, compatibility policy and time when the schema was added to the group. The order in the list matches the order in which schemas were evolved within the group. This call will get a consistent view at the time when the request is processed on the service. So all schemas that were added before this call are returned and all schemas that were deleted before this call are excluded. The execution of this API is non-atomic and if concurrent requests to add or delete schemas are invoked, it may or may not include those schemas in the response.
        Parameters:
        groupId - Id for the group.
        Returns:
        Ordered list of schemas with versions and compatibility policy for all schemas in the group.
        Throws:
        RegistryExceptions.ResourceNotFoundException - if group is not found.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • getSchemaReferences

        java.util.Map<java.lang.String,​io.pravega.schemaregistry.contract.data.VersionInfo> getSchemaReferences​(io.pravega.schemaregistry.contract.data.SchemaInfo schemaInfo)
                                                                                                       throws RegistryExceptions.ResourceNotFoundException,
                                                                                                              RegistryExceptions.UnauthorizedException
        Finds all groups and corresponding version info for the groups where the supplied schema has been registered. It is important to note that the same schema type could be part of multiple group, however in each group it may have gone through a separate evolution. Invocation of this method lists all groups where the specific schema (type, format and binary) is used along with versions that identifies this schema in those groups. The user defined SchemaInfo.properties is not used for comparison.
        Parameters:
        schemaInfo - Schema info to find references for.
        Returns:
        Map of group Id to versionInfo identifier for the schema in that group.
        Throws:
        RegistryExceptions.ResourceNotFoundException - if schema is not found.
        RegistryExceptions.UnauthorizedException - if the user is unauthorized.

      • getNamespace

        java.lang.String getNamespace()
        The Namespace which is used for making all client requests to registry service.
        Returns:
        Namespace used for the client.