Package de.xima.fc.prompt.mgmt.service

Interface IPromptManagementService

  • All Superinterfaces:
    Serializable
    public interface IPromptManagementService
extends Serializable
    Service with various operations for managing prompt connections and queries, mainly CRUD operations.
    Since:
    8.5.0

    • Method Detail

      • analyzePromptConnectionExportData

        IPromptConnectionExportAnalysisResult analyzePromptConnectionExportData​(IPromptConnectionExportAnalysisSpec spec,
                                                                        InputStream inputStream)
                                                                 throws FcPromptException
        Analyzes the given prompt connection export data and returns the analysis result. The input stream is expected to contain a prompt connection export.
        Parameters:
        spec - The specification for analyzing the prompt connection export (e.g., decryption password).
        inputStream - The input stream containing the prompt connection export data.
        Returns:
        The analysis result.
        Throws:
        IllegalArgumentException - If the input stream or spec is null.
        FcPromptException - If an error occurs during the analysis, such as invalid or corrupted data, decryption failure, or unsupported export format.

      • analyzePromptQueryExport

        IPromptQueryExportAnalysisResult analyzePromptQueryExport​(IPromptQueryExportAnalysisSpec spec,
                                                          InputStream inputStream)
                                                   throws FcPromptException
        Analyzes the given prompt query export data and returns the analysis result. The input stream is expected to contain a prompt query export.
        Parameters:
        spec - The specification for analyzing the prompt query export (e.g., decryption password).
        inputStream - The input stream containing the prompt query export data.
        Returns:
        The analysis result.
        Throws:
        IllegalArgumentException - If the input stream or spec is null.
        FcPromptException - If an error occurs during the analysis, such as invalid or corrupted data, decryption failure, or unsupported export format.

      • deleteConnection

        void deleteConnection​(IUser user,
                      PromptObjectIdentifier connection,
                      IPromptLock lock)
               throws FcPromptException
        Deletes the prompt connection with the given ID. If a lock is provided, this operation will fail in case the connection was modified in the meantime.
        Parameters:
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        connection - The ID of the prompt connection to delete, see PromptQueryData.scope() and PromptQueryData.uuid().
        lock - The lock instance returned by lockConnection(IUser, PromptObjectIdentifier). If the connection was modified in the meantime, this operation will fail with a FcPromptException whose cause is a OptimisticLockException.
        Throws:
        FcPromptException - If an error occurs during the deletion.

      • deleteQuery

        void deleteQuery​(IUser user,
                 PromptObjectIdentifier query)
          throws FcPromptException
        Deletes the prompt query with the given ID. If a lock is provided, this operation will fail in case the query was modified in the meantime.
        Parameters:
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        query - The ID of the prompt query to delete, see PromptQueryData.scope() and PromptQueryData.uuid().
        Throws:
        FcPromptException - If an error occurs during the deletion.

      • exportConnectionData

        void exportConnectionData​(IPromptConnectionExportSpec exportSpec,
                          OutputStream outputStream,
                          IUser user)
                   throws FcPromptException
        Exports prompt connection data according to the given export specification and writes it to the given output stream.
        Parameters:
        exportSpec - The specification of what to export and how.
        outputStream - The output stream to write the exported data to.
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        Throws:
        FcPromptException - If an error occurs during the export or the user lacks necessary permissions.
        IllegalArgumentException - If the export specification is invalid or no output stream is provided.

      • exportQueryData

        void exportQueryData​(IPromptQueryExportSpec exportSpec,
                     OutputStream outputStream,
                     IUser user)
              throws FcPromptException
        Exports prompt query data according to the given export specification and writes it to the given output stream.
        Parameters:
        exportSpec - The specification of what to export and how.
        outputStream - The output stream to write the exported data to.
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        Throws:
        FcPromptException - If an error occurs during the export or the user lacks necessary permissions.
        IllegalArgumentException - If the export specification is invalid or no output stream is provided.

      • findConnectionsByType

        List<PromptConnectionData> findConnectionsByType​(IUser user,
                                                 PromptScope scope,
                                                 String type,
                                                 PromptScopeResolutionMode mode)
                                          throws FcPromptException
        Searches for all prompt connections that use a prompt service of the given type.

        The mode parameter controls which connections to include based on their assigned scope. When set to PromptScopeResolutionMode.SELF, only connections assigned to that exact scope are returned. When set to PromptScopeResolutionMode.PARENTS_AND_SELF, connections assigned to the given scope and connections assigned to higher-level scopes are returned. For example, when the scope is a tenant, connections assigned to either that tenant scope or to the global (system) scope are returned.

        Parameters:
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        scope - The scope to which to limit the search, or null to search everywhere.
        type - The type of the connections to search for.
        Returns:
        A list of prompt connections of the given type owned by the given tenant.
        Throws:
        FcPromptException - If an error occurs during the search.

      • findQueryByName

        PromptQueryData findQueryByName​(IUser user,
                                PromptScope scope,
                                String name)
                         throws FcPromptException
        Searches for a prompt query by its name.
        Parameters:
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        scope - The scope of the query, see PromptQueryData.scope().
        name - The name of the query to search for, see PromptQueryData.name().
        Returns:
        The identified prompt query, or null if not found.
        Throws:
        FcPromptException - If an error occurs during the search.

      • importPromptQuery

        IPromptQueryImportResult importPromptQuery​(IPromptQueryImportSpec spec,
                                           InputStream inputStream,
                                           IUser user)
                                    throws FcPromptException
        Imports prompt query data from the given input stream according to the given import specification.
        Parameters:
        spec - The specification for importing the prompt query (e.g., decryption password, target scope).
        inputStream - The input stream containing a prompt query export.
        user - The user who requested the operation.
        Returns:
        The result of the import operation.
        Throws:
        IllegalArgumentException - If the input stream or spec is null.
        FcPromptException - If an error occurs during the import, such as invalid or corrupted data, decryption failure, or unsupported import format.

      • lockConnection

        Locked<IPromptLock,​PromptConnectionData> lockConnection​(IUser user,
                                                              PromptObjectIdentifier connection)
                                                       throws FcPromptException
        Locks the given connection for editing. This method returns a lock instance that should be passed to the various save or delete methods. This will cause those methods to fail in case the connection was modified in the meantime.
        Parameters:
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        connection - The ID of the connection to lock, see PromptQueryData.scope() and PromptQueryData.uuid().
        Returns:
        A lock instance for the given connection.
        Throws:
        FcPromptException - If an error occurs during locking.

      • lockQuery

        Locked<IPromptLock,​PromptQueryData> lockQuery​(IUser user,
                                                    PromptObjectIdentifier query)
                                             throws FcPromptException
        Locks the given query for editing. This method returns a lock instance that should be passed to the various save or delete methods. This will cause those methods to fail in case the query was modified in the meantime.
        Parameters:
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        query - The ID of the query to lock, see PromptQueryData.scope() and PromptQueryData.uuid().
        Returns:
        A lock instance for the given query.
        Throws:
        FcPromptException - If an error occurs during locking.

      • readConnections

        List<PromptConnectionData> readConnections​(IUser user,
                                           PromptScope scope,
                                           PromptScopeResolutionMode mode)
                                    throws FcPromptException
        Reads all prompt connections assigned to the given scope.

        The mode parameter controls which connections to include based on their assigned scope. When set to PromptScopeResolutionMode.SELF, only connections assigned to that exact scope are returned. When set to PromptScopeResolutionMode.PARENTS_AND_SELF, connections assigned to the given scope and connections assigned to higher-level scopes are returned. For example, when the scope is a tenant, connections assigned to either that tenant scope or to the global (system) scope are returned.

        Parameters:
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        scope - The scope whose connections to read, see PromptConnectionData.scope().
        Returns:
        A list of prompt connections owned by the given tenant.
        Throws:
        FcPromptException - If an error occurs during reading.

      • readQueries

        List<PromptQueryData> readQueries​(IUser user,
                                  PromptScope scope,
                                  PromptScopeResolutionMode mode)
                           throws FcPromptException
        Reads all prompt queries assigned to the given scope.

        The mode parameter controls which queries to include based on their assigned scope. When set to PromptScopeResolutionMode.SELF, only queries assigned to that exact scope are returned. When set to PromptScopeResolutionMode.PARENTS_AND_SELF, queries assigned to the given scope and queries assigned to higher-level scopes are returned. For example, when the scope is a tenant, queries assigned to either that tenant scope or to the global (system) scope are returned.

        Parameters:
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        scope - The scope whose queries to read, see PromptQueryData.scope().
        mode - Mode that controls which queries to include.
        Returns:
        A list of prompt queries owned by the given tenant.
        Throws:
        FcPromptException - If an error occurs during reading.

      • readQuery

        PromptQueryData readQuery​(IUser user,
                          PromptObjectIdentifier query)
                   throws FcPromptException
        Reads the prompt query with the given ID.
        Parameters:
        user - The user who requested the operation. Used for permission checks and audit logging. Pass null in case you are performing system-internal operations that should bypass permission checks.
        query - The ID of the prompt query to read.
        Returns:
        The prompt query, or null if not found.
        Throws:
        FcPromptException - If an error occurs during reading.

      • saveConnection

        void saveConnection​(IUser user,
                    PromptConnectionData connection,
                    Object config)
             throws FcPromptException
        Persists (create or update) the given prompt connection in the persistence layer. If a connection with the same ID already exists, it will be updated. Otherwise, a new connection will be created.
        Parameters:
        user - The user who requested the operation.
        connection - The data of the prompt connection to save.
        config - The configuration object for the prompt connection, which will get serialized and persisted. Can also be an instance of SerializedPromptConfig when the data was already serialized.
        Throws:
        FcPromptException - If an error occurs during saving.

      • saveConnection

        IPromptLock saveConnection​(IUser user,
                           PromptConnectionData connection,
                           Object config,
                           IPromptLock lock)
                    throws FcPromptException
        Persists (create or update) the given prompt connection in the persistence layer. If a connection with the same ID already exists, it will be updated. Otherwise, a new connection will be created. When a lock is provided, this operation will fail in case the connection was modified in the meantime.
        Parameters:
        user - The user who requested the operation.
        connection - The data of the prompt connection to save.
        config - The configuration object for the prompt connection, which will get serialized and persisted. Can also be an instance of SerializedPromptConfig when the data was already serialized.
        lock - The lock instance returned by lockConnection(IUser, PromptObjectIdentifier). If the connection was modified in the meantime, this operation will fail with a FcPromptException whose cause is a OptimisticLockException.
        Returns:
        A new lock for the updated connection.
        Throws:
        FcPromptException - If an error occurs during saving.

      • saveQuery

        void saveQuery​(IUser user,
               PromptQueryData query,
               Object config)
        throws FcPromptException
        Persists (create or update) the given prompt query in the persistence layer. If a query with the same ID already exists, it will be updated. Otherwise, a new query will be created.
        Parameters:
        user - The user who requested the operation.
        query - The data of the prompt query to save.
        config - The configuration object for the prompt query, which will get serialized and persisted. Can also be an instance of SerializedPromptConfig when the data was already serialized.
        Throws:
        FcPromptException - If an error occurs during saving.

      • saveQuery

        IPromptLock saveQuery​(IUser user,
                      PromptQueryData query,
                      Object config,
                      IPromptLock lock)
               throws FcPromptException
        Persists (create or update) the given prompt query in the persistence layer. If a query with the same ID already exists, it will be updated. Otherwise, a new query will be created. When a lock is provided, this operation will fail in case the query was modified in the meantime.
        Parameters:
        user - The user who requested the operation.
        query - The data of the prompt query to save.
        config - The configuration object for the prompt query, which will get serialized and persisted. Can also be an instance of SerializedPromptConfig when the data was already serialized.
        lock - The lock instance returned by lockConnection(IUser, PromptObjectIdentifier). If the connection was modified in the meantime, this operation will fail with a FcPromptException whose cause is a OptimisticLockException.
        Returns:
        A new lock for the updated query.
        Throws:
        FcPromptException - If an error occurs during saving.