org.opencastproject.ingest.api.IngestService Maven / Gradle / Ivy
/*
* Licensed to The Apereo Foundation under one or more contributor license
* agreements. See the NOTICE file distributed with this work for additional
* information regarding copyright ownership.
*
*
* The Apereo Foundation licenses this file to you under the Educational
* Community License, Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of the License
* at:
*
* http://opensource.org/licenses/ecl2.txt
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*
*/
package org.opencastproject.ingest.api;
import org.opencastproject.job.api.JobProducer;
import org.opencastproject.mediapackage.MediaPackage;
import org.opencastproject.mediapackage.MediaPackageElementFlavor;
import org.opencastproject.mediapackage.MediaPackageException;
import org.opencastproject.scheduler.api.SchedulerException;
import org.opencastproject.security.api.UnauthorizedException;
import org.opencastproject.util.ConfigurationException;
import org.opencastproject.util.NotFoundException;
import org.opencastproject.workflow.api.WorkflowInstance;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.util.Map;
/**
* Generates {@link MediaPackage}s from media, metadata, and attachments.
*/
public interface IngestService extends JobProducer {
String UTC_DATE_FORMAT = "yyyyMMdd'T'HHmmss'Z'";
String START_DATE_KEY = "ingest_start_date";
/**
* Ingests the compressed mediapackage and starts the workflow as defined by workflowDefinitionID. The
* properties specified in properties will be submitted as configuration data to the workflow.
*
* @param zippedMediaPackage
* A zipped file containing manifest, tracks, catalogs and attachments
* @param workflowDefinitionID
* workflow to be used with this media package
* @param wfConfig
* configuration parameters for the workflow
* @return Workflow instance.
* @throws MediaPackageException
* if the mediapackage contained in the zip stream is invalid
* @throws IOException
* if reading from the input stream fails
* @throws IngestException
* if an unexpected error occurs
* @throws NotFoundException
* if the workflow definition was not found
*/
WorkflowInstance addZippedMediaPackage(InputStream zippedMediaPackage, String workflowDefinitionID,
Map wfConfig) throws MediaPackageException, IOException, IngestException, NotFoundException;
/**
* Ingests the compressed mediapackage and starts the workflow as defined by workflowDefinitionID. The
* properties specified in properties will be submitted as configuration data to the workflow.
*
* The steps defined in that workflow will be appended to the already running workflow instance
* workflowId. If that workflow can't be found, a {@link NotFoundException} will be thrown. If the
* workflowId is null, a new {@link WorkflowInstance} is created.
*
* @param zippedMediaPackage
* A zipped file containing manifest, tracks, catalogs and attachments
* @param workflowDefinitionID
* workflow to be used with this media package
* @param wfConfig
* configuration parameters for the workflow
* @param workflowId
* the workflow instance
* @return Workflow instance.
* @throws MediaPackageException
* if the mediapackage contained in the zip stream is invalid
* @throws IOException
* if reading from the input stream fails
* @throws IngestException
* if an unexpected error occurs
* @throws NotFoundException
* if either one of the workflow definition or workflow instance was not found
* @throws UnauthorizedException
* if the current user does not have {@link org.opencastproject.security.api.Permissions.Action#READ} on the
* workflow instance's mediapackage.
*
* @deprecated As of release 2.4, the scheduler service is able to store a mediapackage. Thereby the concept of the
* pre-procesing workflow is obsolete and there is no more need to resume such a workflow by this method.
*/
@Deprecated
WorkflowInstance addZippedMediaPackage(InputStream zippedMediaPackage, String workflowDefinitionID,
Map wfConfig, Long workflowId) throws MediaPackageException, IOException, IngestException,
NotFoundException, UnauthorizedException;
/**
* Create a new MediaPackage in the repository.
*
* @return The created MediaPackage
* @throws MediaPackageException
* @throws ConfigurationException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage createMediaPackage() throws MediaPackageException, ConfigurationException, IOException, IngestException;
/**
* Create a new MediaPackage in the repository.
* @param mediaPackageID
* The Id for the new Mediapackage
* @return The created MediaPackage
* @throws MediaPackageException
* @throws ConfigurationException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage createMediaPackage(String mediaPackageID) throws MediaPackageException, ConfigurationException,
IOException, IngestException;
/**
* Add a media track to an existing MediaPackage in the repository
*
* @param uri
* The URL of the file to add
* @param flavor
* The flavor of the media that is being added
* @param tags
* Tags to add to the Track
* @param mediaPackage
* The specific Opencast MediaPackage to which Media is being added
* @return MediaPackageManifest The manifest of a specific Opencast MediaPackage element
* @throws MediaPackageException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addTrack(URI uri, MediaPackageElementFlavor flavor, String[] tags, MediaPackage mediaPackage)
throws MediaPackageException, IOException, IngestException;
/**
* Add a media track to an existing MediaPackage in the repository
*
* @param mediaFile
* The media file to add
* @param flavor
* The flavor of the media that is being added
* @param mediaPackage
* The specific Opencast MediaPackage to which Media is being added
* @return MediaPackage The updated Opencast MediaPackage element
* @throws MediaPackageException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addTrack(InputStream mediaFile, String fileName, MediaPackageElementFlavor flavor,
MediaPackage mediaPackage) throws MediaPackageException, IOException, IngestException;
/**
* Add a media track to an existing MediaPackage in the repository
*
* @param mediaFile
* The media file to add
* @param flavor
* The flavor of the media that is being added
* @param tags
* Tags to Add to the Track
* @param mediaPackage
* The specific Opencast MediaPackage to which Media is being added
* @return MediaPackage The updated Opencast MediaPackage element
* @throws MediaPackageException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addTrack(InputStream mediaFile, String fileName, MediaPackageElementFlavor flavor, String [] tags,
MediaPackage mediaPackage) throws MediaPackageException, IOException, IngestException;
/**
* Adds a partial media track to the existing MediaPackage in the repository
*
* @param uri
* the URL of the file to add
* @param flavor
* the flavor of the media that is being added
* @param startTime
* the start time
* @param mediaPackage
* the mediapackage
* @return the updated mediapackage
* @throws IOException
* if reading or writing of the partial track fails
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addPartialTrack(URI uri, MediaPackageElementFlavor flavor, long startTime, MediaPackage mediaPackage)
throws IOException, IngestException;
/**
* Adds a partial media track to the existing MediaPackage in the repository
*
* @param mediaFile
* the media file to add
* @param fileName
* the file name
* @param flavor
* the flavor of the media that is being added
* @param startTime
* the start time
* @param mediaPackage
* the mediapackage
* @return the updated mediapackage
* @throws IOException
* if reading or writing of the partial track fails
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addPartialTrack(InputStream mediaFile, String fileName, MediaPackageElementFlavor flavor,
long startTime, MediaPackage mediaPackage) throws IOException, IngestException;
/**
* Add a [metadata catalog] to an existing MediaPackage in the repository
*
* @param uri
* The URL of the file to add
* @param flavor
* The flavor of the media that is being added
* @param tags
* Tags to add to the catalog
* @param mediaPackage
* The specific Opencast MediaPackage to which Media is being added
* @return MediaPackage The updated Opencast MediaPackage element
* @throws MediaPackageException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addCatalog(URI uri, MediaPackageElementFlavor flavor, String[] tags, MediaPackage mediaPackage)
throws MediaPackageException, IOException, IngestException;
/**
* Add a [metadata catalog] to an existing MediaPackage in the repository
*
* @param catalog
* The catalog file to add
* @param flavor
* The flavor of the media that is being added
* @param mediaPackage
* The specific Opencast MediaPackage to which Media is being added
* @return MediaPackage The updated Opencast MediaPackage element
* @throws MediaPackageException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addCatalog(InputStream catalog, String fileName, MediaPackageElementFlavor flavor,
MediaPackage mediaPackage) throws MediaPackageException, IOException, IngestException;
/**
* Add a [metadata catalog] to an existing MediaPackage in the repository
*
* @param catalog
* The catalog file to add
* @param flavor
* The flavor of the media that is being added
* @param tags
* The tags for the media that is being added:
* @param mediaPackage
* The specific Opencast MediaPackage to which Media is being added
* @return MediaPackage The updated Opencast MediaPackage element
* @throws IllegalArgumentException
* if the data passed to this method are not valid
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addCatalog(InputStream catalog, String fileName, MediaPackageElementFlavor flavor, String[] tags,
MediaPackage mediaPackage) throws IllegalArgumentException, IOException, IngestException;
/**
* Add an attachment to an existing MediaPackage in the repository
*
* @param uri
* The URL of the file to add
* @param flavor
* The flavor of the media that is being added
* @param tags
* Tags to add to the attachment
* @param mediaPackage
* The specific Opencast MediaPackage to which Media is being added
* @return MediaPackage The updated Opencast MediaPackage element
* @throws MediaPackageException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addAttachment(URI uri, MediaPackageElementFlavor flavor, String[] tags, MediaPackage mediaPackage)
throws MediaPackageException, IOException, IngestException;
/**
* Add an attachment to an existing MediaPackage in the repository
*
* @param file
* The file to add
* @param flavor
* The flavor of the media that is being added
* @param mediaPackage
* The specific Opencast MediaPackage to which Media is being added
* @return MediaPackage The updated Opencast MediaPackage element
* @throws MediaPackageException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addAttachment(InputStream file, String fileName, MediaPackageElementFlavor flavor,
MediaPackage mediaPackage) throws MediaPackageException, IOException, IngestException;
/**
* Add an attachment to an existing MediaPackage in the repository
*
* @param file
* The file to add
* @param flavor
* The flavor of the media that is being added
* @param tags
* The tags of the media thas is being added
* @param mediaPackage
* The specific Opencast MediaPackage to which Media is being added
* @return MediaPackage The updated Opencast MediaPackage element
* @throws MediaPackageException
* @throws IOException
* @throws IngestException
* if an unexpected error occurs
*/
MediaPackage addAttachment(InputStream file, String fileName, MediaPackageElementFlavor flavor, String[] tags,
MediaPackage mediaPackage) throws MediaPackageException, IOException, IngestException;
/**
* Ingests the mediapackage and starts the default workflow as defined by the
* org.opencastproject.workflow.default.definition key, found in the system configuration.
*
* @param mediaPackage
* The specific Opencast MediaPackage being ingested
* @return Workflow instance id.
* @throws IngestException
* if an unexpected error occurs
*/
WorkflowInstance ingest(MediaPackage mediaPackage) throws IllegalStateException, IngestException;
/**
* Ingests the mediapackage and starts the workflow as defined by workflowDefinitionID. The properties
* specified in properties will be submitted as configuration data to the workflow.
*
* @param mediaPackage
* The specific Opencast MediaPackage being ingested
* @param workflowDefinitionID
* workflow to be used with this media package
* @param properties
* configuration properties for the workflow
* @return Workflow instance id.
* @throws IngestException
* if an unexpected error occurs
* @throws NotFoundException
* if the workflow defintion can't be found
*/
WorkflowInstance ingest(MediaPackage mediaPackage, String workflowDefinitionID, Map properties)
throws IllegalStateException, IngestException, NotFoundException;
/**
* Ingests the mediapackage and starts the workflow as defined by workflowDefinitionID. The properties
* specified in properties will be submitted as configuration data to the workflow.
*
* The steps defined in that workflow will be appended to the already running workflow instance
* workflowId. If that workflow can't be found, a {@link NotFoundException} will be thrown. If the
* workflowId is null, a new {@link WorkflowInstance} is created.
*
* @param mediaPackage
* The specific Opencast MediaPackage being ingested
* @param workflowDefinitionID
* workflow to be used with this media package
* @param properties
* configuration properties for the workflow
* @param workflowId
* the workflow identifier
* @return Workflow instance id.
* @throws IngestException
* if an unexpected error occurs
* @throws NotFoundException
* if either one of the workflow definition or workflow instance was not found
* @throws UnauthorizedException
* if the current user does not have {@link org.opencastproject.security.api.Permissions.Action#READ} on the
* workflow instance's mediapackage.
*
* @deprecated As of release 2.4, the scheduler service is able to store a mediapackage. Thereby the concept of the
* pre-procesing workflow is obsolete and there is no more need to resume such a workflow by this method.
*/
@Deprecated
WorkflowInstance ingest(MediaPackage mediaPackage, String workflowDefinitionID, Map properties,
Long workflowId) throws IllegalStateException, IngestException, NotFoundException, UnauthorizedException;
/**
* Schedule an event with a given media package.
*
* @param mediaPackage
* The specific Opencast MediaPackage being ingested
* @param workflowDefinitionID
* workflow to be used with this media package
* @param properties
* configuration properties for the workflow
* @throws IngestException
* if an unexpected error occurs
* @throws NotFoundException
* if the workflow defintion can't be found
*/
void schedule(MediaPackage mediaPackage, String workflowDefinitionID, Map properties)
throws IllegalStateException, IngestException, NotFoundException, UnauthorizedException, SchedulerException;
/**
* Delete an existing MediaPackage and any linked files from the temporary ingest filestore.
*
* @param mediaPackage
* The specific Opencast MediaPackage
* @throws IngestException
* if an unexpected error occurs
*/
void discardMediaPackage(MediaPackage mediaPackage) throws IOException, IngestException;
}