Package org.corpus_tools.pepper.impl

Class PepperModuleImpl

java.lang.Object

org.corpus_tools.pepper.impl.PepperModuleImpl

All Implemented Interfaces:

Thread.UncaughtExceptionHandler, PepperModule

Direct Known Subclasses:

PepperExporterImpl, PepperImporterImpl, PepperManipulatorImpl

public class PepperModuleImpl
extends Object
implements PepperModule, Thread.UncaughtExceptionHandler

TODO make docu

Author:

Florian Zipser

Field Summary

Fields

Modifier and Type	Field	Description
protected boolean	isMultithreaded
protected org.slf4j.Logger	logger
protected ModuleController	moduleController	the controller object, which acts as bridge between Pepper framework and Pepper module.
protected org.eclipse.emf.common.util.URI	resources	TODO make docu
protected org.corpus_tools.salt.common.SaltProject	saltProject	Salt project which is processed by module.
protected org.corpus_tools.salt.common.SCorpusGraph	sCorpusGraph	The SCorpusGraph object which should be processed by this module.
protected String	symbolicName	TODO make docu
protected org.eclipse.emf.common.util.URI	temproraries	Deprecated.

Fields inherited from interface org.corpus_tools.pepper.modules.PepperModule

ENDING_ALL_FILES, ENDING_FOLDER, ENDING_LEAF_FOLDER, ENDING_TAB, ENDING_TXT, ENDING_XML

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	PepperModuleImpl()	Creates a PepperModule object, which is either a MODULE_TYPE.IMPORTER, a MODULE_TYPE.MANIPULATOR or a MODULE_TYPE.EXPORTER.
protected	PepperModuleImpl(String name)	Creates a PepperModule object, which is either a MODULE_TYPE.IMPORTER, a MODULE_TYPE.MANIPULATOR or a MODULE_TYPE.EXPORTER.

Method Summary

Modifier and Type	Method	Description
protected void	activate(org.osgi.service.component.ComponentContext componentContext)	This method is called by OSGi framework and sets the component context, this class is running in.
PepperMapper	createPepperMapper(org.corpus_tools.salt.graph.Identifier sElementId)	OVERRIDE THIS METHOD FOR CUSTOMIZED MAPPING.
void	done(PepperMapperController controller)	This method is called by a PepperMapperController object to notify the PepperModule object, that the mapping is done.
void	done(org.corpus_tools.salt.graph.Identifier id, DOCUMENT_STATUS result)	This method is called by a PepperMapperController object to notify the PepperModule object, that the mapping for this object is done.
void	end()	Calls method start(Identifier) for every root SCorpus of SaltProject object.
org.osgi.service.component.ComponentContext	getComponentContext()	Returns the ComponentContext of the OSGi environment the bundle was started in.
org.corpus_tools.salt.common.SCorpusGraph	getCorpusGraph()	Returns the SCorpusGraph object which is filled, manipulated or exported by the current module.
String	getDesc()	Returns a short description of this module.
protected Map<String,DocumentController>	getDocumentId2DC()	Returns the map relating Identifier belonging to SDocument objects to their DocumentController container.
PepperModuleDesc	getFingerprint()	Returns a PepperModuleDesc object, which is a kind of a fingerprint of this PepperModule.
protected Map<String,PepperMapperController>	getMapperControllers()	Returns a threadsafe map of all PepperMapperController objects which are connected with a started PepperMapper corresponding to their
protected ThreadGroup	getMapperThreadGroup()	Returns a ThreadGroup where PepperMapper objects and the corresponding threads are supposed to run in.
ModuleController	getModuleController()	Returns the container and controller object for the current module.
MODULE_TYPE	getModuleType()	Returns the type of this module.
String	getName()	Returns the name of this module.
Double	getProgress()	{@inheritDoc PepperModule#getProgress()}
Double	getProgress(String globalId)	This method is invoked by the Pepper framework, to get the current progress concerning the SDocument object corresponding to the given Identifier in percent.
PepperModuleProperties	getProperties()	Returns a PepperModuleProperties object containing properties to customize the behavior of this PepperModule.
org.eclipse.emf.common.util.URI	getResources()	Returns the path of the folder which might contain resources for a Pepper module.
org.corpus_tools.salt.common.SaltProject	getSaltProject()	Returns the SaltProject object, which is filled, manipulated or exported by the current module.
SelfTestDesc	getSelfTestDesc()	This method is called by the Pepper framework to run an integration test for module.
Collection<String>	getStartProblems()	If PepperModule.isReadyToStart() has returned false, this method returns a list of reasons why this module is not ready to start.
org.eclipse.emf.common.util.URI	getSupplierContact()	Returns a uri where to find more information about this module and where to find some contact information to contact the supplier.
org.eclipse.emf.common.util.URI	getSupplierHomepage()	Sets the URI to the homepage describing the functionality of the module.
String	getSymbolicName()	Returns the symbolic name of this OSGi bundle.
org.eclipse.emf.common.util.URI	getTemproraries()	Deprecated.
String	getVersion()	Returns the version of this module.
boolean	isMultithreaded()	Returns whether this PepperModule is able to run multithreaded.
boolean	isReadyToStart()	This method is called by the pepper framework after initializing this object and directly before start processing.
List<org.corpus_tools.salt.graph.Identifier>	proposeImportOrder(org.corpus_tools.salt.common.SCorpusGraph sCorpusGraph)	This method could be overridden, to make a proposal for the import order of SDocument objects.
void	setCorpusGraph(org.corpus_tools.salt.common.SCorpusGraph newSCorpusGraph)	Sets the SCorpusGraph object which is filled, manipulated or exported by the current module.
void	setDesc(String desc)	Sets a short description of this module.
void	setIsMultithreaded(boolean isMultithreaded)	Sets whether this PepperModule is able to run multithreaded.
protected void	setMapperThreadGroup(ThreadGroup mapperThreadGroup)	Sets a ThreadGroup where PepperMapper objects and the corresponding threads are supposed to run in.
protected void	setName(String name)	Sets the name of this PepperModule.
void	setPepperModuleController(ModuleController newModuleController)	Sets the container and controller object for the current module.
void	setPepperModuleController_basic(ModuleController newModuleController)	Sets the container and controller object for the current module.
void	setProperties(PepperModuleProperties properties)	Sets thePepperModuleProperties object containing properties to customize the behavior of this PepperModule.
void	setResources(org.eclipse.emf.common.util.URI newResources)	Sets the resource folder used by PepperModule.getResources().
void	setSaltProject(org.corpus_tools.salt.common.SaltProject newSaltProject)	Sets the SaltProject object, which is filled, manipulated or exported by the current module.
void	setSupplierContact(org.eclipse.emf.common.util.URI supplierContact)	Sets a uri where to find more information about this module and where to find some contact information to contact the supplier.
void	setSupplierHomepage(org.eclipse.emf.common.util.URI hp)	Returns the URI to the homepage describing the functionality of the module.
void	setSymbolicName(String newSymbolicName)	Sets the symbolic name of this OSGi bundle.
void	setTemproraries(org.eclipse.emf.common.util.URI newTemproraries)	Deprecated.
void	setVersion(String newVersion)	Sets the version of this module.
void	start()	Starts the conversion process.
void	start(org.corpus_tools.salt.graph.Identifier sElementId)	This method is called by method start(), if the method was not overridden by the current class.
String	toString()	Returns a string representation of this object.
void	uncaughtException(Thread t, Throwable e)	Method catches Uncaught exceptions thrown by PepperMapperImpl while running as Thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

logger

protected org.slf4j.Logger logger

saltProject

protected org.corpus_tools.salt.common.SaltProject saltProject

Salt project which is processed by module.

resources

protected org.eclipse.emf.common.util.URI resources

TODO make docu

temproraries

@Deprecated
protected org.eclipse.emf.common.util.URI temproraries

Deprecated.

TODO make docu

symbolicName

protected String symbolicName

TODO make docu

moduleController

protected ModuleController moduleController

the controller object, which acts as bridge between Pepper framework and Pepper module.

sCorpusGraph

protected org.corpus_tools.salt.common.SCorpusGraph sCorpusGraph

The SCorpusGraph object which should be processed by this module.

isMultithreaded

protected boolean isMultithreaded

Constructor Detail

PepperModuleImpl

protected PepperModuleImpl()

Creates a PepperModule object, which is either a MODULE_TYPE.IMPORTER, a MODULE_TYPE.MANIPULATOR or a MODULE_TYPE.EXPORTER. The name of this module is set to "MyModule".
We recommend to use the constructor PepperModuleImpl(String) and pass a proper name.

PepperModuleImpl

protected PepperModuleImpl(String name)

Creates a PepperModule object, which is either a MODULE_TYPE.IMPORTER, a MODULE_TYPE.MANIPULATOR or a MODULE_TYPE.EXPORTER. The passed name is set as the modules name.

Method Detail

getFingerprint

public PepperModuleDesc getFingerprint()

Returns a PepperModuleDesc object, which is a kind of a fingerprint of this PepperModule. This fingerprint for instance contains information like the name, the version of this module or information about the supplier.

Specified by:

getFingerprint in interface PepperModule

Returns:

fingerprint to this module

getName

public String getName()

Returns the name of this module. In most cases, the name somehow describes the task of the module.

Specified by:

getName in interface PepperModule

Returns:

the value of the 'Name' attribute.

setName

protected void setName(String name)

Sets the name of this PepperModule. Note, that a name can only be set once and not be changed again.

Parameters:

name - name of this module.

getVersion

public String getVersion()

Returns the version of this module.

Specified by:

getVersion in interface PepperModule

Returns:

the value of the 'Version' attribute.

setVersion

public void setVersion(String newVersion)

Sets the version of this module. The version normally is set internally, this method only exists for dependency injection, by the modules project itself. But this method is never called by the pepper framework.

Specified by:

setVersion in interface PepperModule

Parameters:

newVersion - the new value of the 'Version' attribute.

getModuleType

public MODULE_TYPE getModuleType()

Returns the type of this module.

Specified by:

getModuleType in interface PepperModule

Returns:

getDesc

public String getDesc()

Returns a short description of this module. Please support some information, for the user, of what task this module does.

Specified by:

getDesc in interface PepperModule

Returns:

a short description of the task of this module

setDesc

public void setDesc(String desc)

Sets a short description of this module. Please support some information, for the user, of what task this module does.

Specified by:

setDesc in interface PepperModule

Parameters:

desc - a short description of the task of this module

getSupplierContact

public org.eclipse.emf.common.util.URI getSupplierContact()

Returns a uri where to find more information about this module and where to find some contact information to contact the supplier.

Specified by:

getSupplierContact in interface PepperModule

Returns:

contact address like eMail address or homepage address

setSupplierContact

public void setSupplierContact(org.eclipse.emf.common.util.URI supplierContact)

Sets a uri where to find more information about this module and where to find some contact information to contact the supplier.

Specified by:

setSupplierContact in interface PepperModule

getSupplierHomepage

public org.eclipse.emf.common.util.URI getSupplierHomepage()

Description copied from interface: PepperModule

Sets the URI to the homepage describing the functionality of the module.

Specified by:

getSupplierHomepage in interface PepperModule

Returns:

URI to the homepage

setSupplierHomepage

public void setSupplierHomepage(org.eclipse.emf.common.util.URI hp)

Description copied from interface: PepperModule

Returns the URI to the homepage describing the functionality of the module.

Specified by:

setSupplierHomepage in interface PepperModule

Parameters:

hp - URI to the homepage

getProperties

public PepperModuleProperties getProperties()

Returns a PepperModuleProperties object containing properties to customize the behavior of this PepperModule.

Specified by:

getProperties in interface PepperModule

Returns:

setProperties

public void setProperties(PepperModuleProperties properties)

Sets thePepperModuleProperties object containing properties to customize the behavior of this PepperModule. Please make sure, that this method is called in constructor of your module. If not, a general PepperModuleProperties object is created by the pepper framework and will be initialized. This means, when calling this method later, all properties for customizing the module will be overridden.

Specified by:

setProperties in interface PepperModule

getSaltProject

public org.corpus_tools.salt.common.SaltProject getSaltProject()

Returns the SaltProject object, which is filled, manipulated or exported by the current module.

Specified by:

getSaltProject in interface PepperModule

Returns:

the value of the 'Salt Project' attribute.

setSaltProject

public void setSaltProject(org.corpus_tools.salt.common.SaltProject newSaltProject)

Sets the SaltProject object, which is filled, manipulated or exported by the current module. Note: This method only should be called by the pepper framework.

Specified by:

setSaltProject in interface PepperModule

Parameters:

newSaltProject - the new value of the 'Salt Project' attribute.

getResources

public org.eclipse.emf.common.util.URI getResources()

Returns the path of the folder which might contain resources for a Pepper module. This is the folder, which is delivered as part of the modules zip. Usually a Pepper module is a zip file containing a jar file and a folder having the same name as the jar file. In default configuration all files of folder "./src/main/resources" are copied to the resource folder.

Specified by:

getResources in interface PepperModule

Returns:

path to resources

setResources

public void setResources(org.eclipse.emf.common.util.URI newResources)

Sets the resource folder used by PepperModule.getResources(). This method should only be invoked by the Pepper framework. The documentation of PepperModule.getResources() for more details.

Specified by:

setResources in interface PepperModule

Parameters:

newResources - path to resource folder

getTemproraries

@Deprecated
public org.eclipse.emf.common.util.URI getTemproraries()

Deprecated.

TODO make docu

Specified by:

getTemproraries in interface PepperModule

setTemproraries

@Deprecated
public void setTemproraries(org.eclipse.emf.common.util.URI newTemproraries)

Deprecated.

TODO make docu

Specified by:

setTemproraries in interface PepperModule

getSymbolicName

public String getSymbolicName()

Returns the symbolic name of this OSGi bundle.

Specified by:

getSymbolicName in interface PepperModule

Returns:

the value of the 'Symbolic Name' attribute.

setSymbolicName

public void setSymbolicName(String newSymbolicName)

Sets the symbolic name of this OSGi bundle. This value is set automatically inside the activate method, which is implemented in PepperModuleImpl class. If you want to manipulate that method. make sure to set the symbolic name and make sure, that it is set to the bundles symbolic name.

Specified by:

setSymbolicName in interface PepperModule

Parameters:

newSymbolicName - the new value of the 'Symbolic Name' attribute.

getComponentContext

public org.osgi.service.component.ComponentContext getComponentContext()

Returns the ComponentContext of the OSGi environment the bundle was started in.

Specified by:

getComponentContext in interface PepperModule

Returns:

activate

protected void activate(org.osgi.service.component.ComponentContext componentContext)

This method is called by OSGi framework and sets the component context, this class is running in. This method scans the given ComponentContext object for symbolic name and version and initializes its values symbolicName and #version with it. When running this class in OSGi context, you do not have to set both values by hand. With the given architecture, the symbolic name and the bundle version will be given by pom.xml, via MANIFEST.MF and finally read by this method. Also sets the internal field storing the ComponentContext which can be retrieved via getComponentContext().

Parameters:

componentContext -

getStartProblems

public Collection<String> getStartProblems()

If PepperModule.isReadyToStart() has returned false, this method returns a list of reasons why this module is not ready to start.

Specified by:

getStartProblems in interface PepperModule

Returns:

a list describing the reasons, or an empty list if there were no problems

isReadyToStart

public boolean isReadyToStart()
                       throws PepperModuleNotReadyException

This method is called by the pepper framework after initializing this object and directly before start processing. Initializing means setting properties PepperModuleProperties, setting temporary files, resources etc. . returns false or throws an exception in case of PepperModule instance is not ready for any reason
This method is also called, when Pepper is in self-test mode, to check if module is correctly instantiated.
The default implementation checks:

• if a path to resource folder is given
• if the MODULE_TYPE is not null
• if the name is not null

When overriding this method, please call super.isReadyToStart() first and in case a problem occured add it to the list PepperModule.getStartProblems().

Specified by:

isReadyToStart in interface PepperModule

Returns:

false, PepperModule instance is not ready for any reason, true, else.

Throws:

PepperModuleNotReadyException

getModuleController

public ModuleController getModuleController()

Returns the container and controller object for the current module. The ModuleController object is a kind of communicator between a PepperModule and the pepper framework.

Specified by:

getModuleController in interface PepperModule

Returns:

the value of the 'Pepper Module Controller' container reference.

setPepperModuleController

public void setPepperModuleController(ModuleController newModuleController)

Sets the container and controller object for the current module. The ModuleController object is a kind of communicator between a PepperModule and the pepper framework. Also calls the inverse method ModuleController.setPepperModule_basic(PepperModule) . Note, this method only should be called by pepper framework.

Specified by:

setPepperModuleController in interface PepperModule

Parameters:

newModuleController - the new value of the 'Pepper Module Controller' container reference.

setPepperModuleController_basic

public void setPepperModuleController_basic(ModuleController newModuleController)

Sets the container and controller object for the current module. The ModuleController object is a kind of communicator between a PepperModule and the pepper framework. Note, this method only should be called by pepper framework.

Specified by:

setPepperModuleController_basic in interface PepperModule

Parameters:

newModuleController - the new value of the 'Pepper Module Controller' container reference.

getCorpusGraph

public org.corpus_tools.salt.common.SCorpusGraph getCorpusGraph()

Returns the SCorpusGraph object which is filled, manipulated or exported by the current module. The SCorpusGraph object is contained in the salt project PepperModule.getSaltProject().

Specified by:

getCorpusGraph in interface PepperModule

Returns:

the value of the 'SCorpus Graph' attribute.

setCorpusGraph

public void setCorpusGraph(org.corpus_tools.salt.common.SCorpusGraph newSCorpusGraph)

Sets the SCorpusGraph object which is filled, manipulated or exported by the current module. The SCorpusGraph object is contained in the salt project PepperModule.getSaltProject(). Note: This method only should be called by the pepper framework.

Specified by:

setCorpusGraph in interface PepperModule

Parameters:

newSCorpusGraph - the new value of the 'SCorpus Graph' attribute.

getMapperControllers

protected Map<String,PepperMapperController> getMapperControllers()

Returns a threadsafe map of all PepperMapperController objects which are connected with a started PepperMapper corresponding to their

Returns:

setIsMultithreaded

public void setIsMultithreaded(boolean isMultithreaded)

Sets whether this PepperModule is able to run multithreaded. This method only should be called by the module itself.

Specified by:

setIsMultithreaded in interface PepperModule

isMultithreaded

public boolean isMultithreaded()

Returns whether this PepperModule is able to run multithreaded. The behavior only should be set by the module itself via calling PepperModule.setIsMultithreaded(boolean).

Specified by:

isMultithreaded in interface PepperModule

Returns:

true, if module can run in multithread mode.

getMapperThreadGroup

protected ThreadGroup getMapperThreadGroup()

Returns a ThreadGroup where PepperMapper objects and the corresponding threads are supposed to run in.

Returns:

setMapperThreadGroup

protected void setMapperThreadGroup(ThreadGroup mapperThreadGroup)

Sets a ThreadGroup where PepperMapper objects and the corresponding threads are supposed to run in.

Parameters:

mapperThreadGroup -

getDocumentId2DC

protected Map<String,DocumentController> getDocumentId2DC()

Returns the map relating Identifier belonging to SDocument objects to their DocumentController container.

Returns:

map

start

public void start()
           throws PepperModuleException

Starts the conversion process. This method is the main method of a pepper module. If this method is not overridden, it will call PepperModule.start(Identifier) for each SDocument and SCorpus object being contained in the set SCorpusGraph. This is done in a multithreaded way by default. Note: When your module should not run in multithreaded mode, call PepperModule.setIsMultithreaded(boolean) .

Specified by:

start in interface PepperModule

Throws:

PepperModuleException

done

public void done(org.corpus_tools.salt.graph.Identifier id,
                 DOCUMENT_STATUS result)

This method is called by a PepperMapperController object to notify the PepperModule object, that the mapping for this object is done.

Specified by:

done in interface PepperModule

done

public void done(PepperMapperController controller)

This method is called by a PepperMapperController object to notify the PepperModule object, that the mapping is done.

Specified by:

done in interface PepperModule

Parameters:

controller - The object which is done with its job

start

public void start(org.corpus_tools.salt.graph.Identifier sElementId)
           throws PepperModuleException

This method is called by method start(), if the method was not overridden by the current class. If this is not the case, this method will be called for every document which has to be processed.

Specified by:

start in interface PepperModule

Parameters:

sElementId - the id value for the current document or corpus to process

Throws:

PepperModuleException

createPepperMapper

public PepperMapper createPepperMapper(org.corpus_tools.salt.graph.Identifier sElementId)

OVERRIDE THIS METHOD FOR CUSTOMIZED MAPPING. This method creates a customized PepperMapper object and returns it. You can here do some additional initialisations. Thinks like setting the Identifier of the SDocument or SCorpus object and the URI resource is done by the framework (or more in detail in method PepperModule.start()). The parameter sElementId, if a PepperMapper object should be created in case of the object to map is either an SDocument object or an SCorpus object of the mapper should be initialized differently.
Note: Override this method.

Specified by:

createPepperMapper in interface PepperModule

Parameters:

sElementId - Identifier of the SCorpus or SDocument to be processed.

Returns:

PepperMapper object to do the mapping task for object connected to given Identifier

end

public void end()
         throws PepperModuleException

Calls method start(Identifier) for every root SCorpus of SaltProject object.

Specified by:

end in interface PepperModule

Throws:

PepperModuleException

uncaughtException

public void uncaughtException(Thread t,
                              Throwable e)

Method catches Uncaught exceptions thrown by PepperMapperImpl while running as Thread. This method just logs the exception. It is assumed, that the PepperMapperImpl itself notifies the Pepper framework about the unsuccessful process.

Specified by:

uncaughtException in interface Thread.UncaughtExceptionHandler

getProgress

public Double getProgress(String globalId)

This method is invoked by the Pepper framework, to get the current progress concerning the SDocument object corresponding to the given Identifier in percent. A valid value return must be between 0 and 1.
Note: In case, you have overridden the method PepperModule.start(Identifier) or PepperModule.start(), please also override this method, because it accesses an internal list of all mappers, which initialized in PepperModule.start(Identifier).

Specified by:

getProgress in interface PepperModule

getProgress

public Double getProgress()

{@inheritDoc PepperModule#getProgress()}

Specified by:

getProgress in interface PepperModule

Returns:

the progress of all documents processed by this module

proposeImportOrder

public List<org.corpus_tools.salt.graph.Identifier> proposeImportOrder(org.corpus_tools.salt.common.SCorpusGraph sCorpusGraph)

This method could be overridden, to make a proposal for the import order of SDocument objects. Overriding this method is useful, in case of the order matters in the specific mapping of this PepperModule . In this case a influencing the import order can decrease the processing time. If you do not want to influence the order, just return an empty list, or don't override this method.
In case you want to override this method, you can return a value for each passed SCorpusGraph.
OVERRIDE THIS METHOD FOR CUSTOMIZED MAPPING.

Specified by:

proposeImportOrder in interface PepperModule

Parameters:

sCorpusGraph - the SCorpusGraph object for which the order could be proposed

Returns:

a list determining the import order of SDocument objects

toString

public String toString()

Returns a string representation of this object.
Note: This representation cannot be used for serialization/ deserialization purposes.

Overrides:

toString in class Object

getSelfTestDesc

public SelfTestDesc getSelfTestDesc()

Description copied from interface: PepperModule

This method is called by the Pepper framework to run an integration test for module. When the method returns null, it means that no integration test is supported. Otherwise, the SelfTestDesc object needs to provide an input corpus path and an output corpus path. When this module is:

• an importer: SelfTestDesc.getInputCorpusPath() should contain the format to be imported. SelfTestDesc.getExpectedCorpusPath() should contain the expected salt project (for control).
• a manipulator: SelfTestDesc.getInputCorpusPath() should contain a salt project which is the module's input. SelfTestDesc.getExpectedCorpusPath() should contain the expected salt project (for control).
• an exporter: SelfTestDesc.getInputCorpusPath() should contain a salt project which is the module's input. SelfTestDesc.getExpectedCorpusPath() should contain the expected corpus in output format.

The simplest way to create a test description is:

 return new IntegrationTestDesc(inputPath, outputPath);
 

When this module is an importer or a manipulator the method SelfTestDesc.compare(SaltProject, SaltProject) is called to compare output salt project with expected salt project. When the module is an exporter the method SelfTestDesc.compare(URI, URI) is called to compare the created output folder with an expected one. By default this method checks whether the file structure and each file is equal.

Specified by:

getSelfTestDesc in interface PepperModule

Returns:

test description