 |
CatNiP docutest
Sähköinen nuottikirja, HY-TKTKL-OHTUPROJ KESÄ11
|
A combination of factory methods and helper object instance methods which facilitate the reading of data from the Internet Music Score Library Project, a MediaWiki site containing music scores. More...
#import <IMSLPQueryHelper.h>
Public Types | |
| enum | MWStatus { MWQueryNoStatus = 1 << 0, MWQueryStarting = 1 << 1, MWQueryInProgress = 1 << 2, MWQueryCompleted = 1 << 3, MWQueryFailed = 1 << 4, MWQueryCancelled = 1 << 5 } |
| Enumerates the different statuses available for IMSLPQueryHelper instances. More... | |
Public Member Functions | |
| (void) | - categoryParseFailed: [implementation] |
| Implementation of MediaWikiCategoryQueryDelegate method. | |
| (void) | - dealloc [implementation] |
| Custom dealloc implementation to release worker objects etc. | |
| (void) | - didFinishDownload: [implementation] |
| Implementation of MediaWikiDownloadDelegate method. | |
| (void) | - didReceiveCategoryArray: [implementation] |
| Implementation of MediaWikiCategoryQueryDelegate method. | |
| (void) | - didReceiveCompositionData: [implementation] |
| Implementation of MediaWikiPageQueryDelegate method. | |
| (float) | - getDownloadProgress |
| An IMSLPQueryHelper worker object instance method to report the current download progress of a file. | |
| (id) | - initWithCategory:intoArray: |
| init method for the IMSLPQueryHelper worker object. | |
| (id) | - initWithTitle: |
| init method for the IMSLPQueryHelper worker object. | |
| (void) | - progressUpdate: [implementation] |
| Implementation of the MediaWikiProgressListener method. | |
| (void) | - startCategoryFetch |
| Starts the category query encapsulated by this worker object. | |
| (void) | - startDownload |
| The starting point method for file download work. | |
| (void) | - startPageFetch |
| Starts the page (composition data) read operation. | |
Static Public Member Functions | |
| (BOOL) | + abortAllReads |
| Signals the need to abort all currently ongoing IMSLP read operations. | |
| (BOOL) | + abortRead: |
| Aborts the requested read. | |
| (float) | + downloadProgressFor: |
| Returns a value between 0.0 and 1.0 describing the download progress for the given file name. | |
| (NSString *) | + imslpAPIURL |
| Static method returning the current IMSLP API url. | |
| (NSString *) | + imslpFetchURL |
| Static method returning the current IMSLP page fetch URL. | |
| (NSString *) | + imslpFileURL |
| Static method returning the current IMSLP file download URL. | |
| (void) | + initialize [implementation] |
| Initializes the class. | |
| (int) | + queryStatusFor: |
| Returns a more detailed query status against the given destination. | |
| (BOOL) | + readIMSLPCategory:reportTo:withMethod: [implementation] |
| Begin reading a category from IMSLP, writing the results into an array and report progress to the defined target object and method. | |
| (BOOL) | + readIMSLPFile:ofComposition:reportTo:withMethod: |
| A factory method for downloading a file from IMSLP to local storage. | |
| (BOOL) | + readIMSLPPage:composerName:reportTo:withMethod: |
| Read a IMSLP (composition) wiki page parsing composition music scores into an IMSLPCompositionData object and report it to the object and method given. | |
| (BOOL) | + readInProgressFor: |
| Checks whether there is an active read operation against the given destination. | |
| (void) | + setImslpAPIURL: |
| Static method to set the IMSLP API URL. | |
| (void) | + setImslpFetchURL: |
| Static method to set the ISMLP page fetch URL. | |
| (void) | + setImslpFileURL: |
| Static method to set the IMSLP file download URL. | |
Properties | |
| NSString * | categoryName |
| The full MediaWiki category name for a category contents query. | |
| NSString * | composerName |
| The composer name for composer "contents" queries in IMSLP. | |
| NSString * | pageTitle |
| The page title for composition score list queries. | |
| int | queryStatus |
| A more detailed query status property, uses the local enum MWStatus. | |
| BOOL | stopRequested |
| A simple flag telling the worker object whether it should stop working. | |
| NSMutableArray * | targetArray |
| The array into which category contents are read. | |
| SEL | targetMethod |
| The method signature describing to which method in the target object the helper should send progress reports to. | |
| id | targetObject |
| The target object which shall receive progress reports by calling the specified targetMethod. | |
| CompositionData * | thisComposition |
| Composition data retained so that it can be given back to the read requester upon completion. | |
| BOOL | working |
| A simple flag telling whether the worker object is working or not. | |
A combination of factory methods and helper object instance methods which facilitate the reading of data from the Internet Music Score Library Project, a MediaWiki site containing music scores.
The query helper objects currently utilize three different types of query objects to fetch data from IMSLP. MediaWikiCategoryQuery instances are used to fetch category (XML) data from IMSLP (ie. lists of composers and lists of compositions by composer). MediaWikiPageQuery instances are used to fetch information from a single composition (ie. the list of music scores). Finally MediaWikiDownload instances are used to fetch an actual music score file.
The implementation of the query procedure is currently slightly ugly. IMSLPQueryHelper is not subclassed into different types depending on the helper object type separately, but instead has different initialization methods and different work start methods for different types of tasks. This is an "action point" for later refactoring.
Created by Antti V J Niemela, tkol on 5/30/11. Copyright 2011 University of Helsinki. All rights reserved.
| - (enum) MWStatus |
Enumerates the different statuses available for IMSLPQueryHelper instances.
| + (BOOL) abortAllReads |
Signals the need to abort all currently ongoing IMSLP read operations.
All currently ongoing IMSLP read operations will be sent a setStopRequested message, which will cause them to stop reading after their current parse is over. The data generated by the parse will not be added to the specified mutable data types.
| + (BOOL) abortRead: | (NSString*) | destination |
Aborts the requested read.
| - (void) categoryParseFailed: | (NSError *) | error | [implementation] |
Implementation of MediaWikiCategoryQueryDelegate method.
Receives any XML parse/validation errors encountered by the MediaWikiCategoryQuery
| error | The error encountered. |
| - (void) dealloc | [implementation] |
Custom dealloc implementation to release worker objects etc.
| - (void) didFinishDownload: | (NSString *) | loadedFilePath | [implementation] |
Implementation of MediaWikiDownloadDelegate method.
Receives an NSString object which represents the file path where the downloaded file was saved. Passes it on to the object and method given in the factory method call, requiring a signature of (void)methodName:(NSArray*)twoElementsFirstIsFileNameSecondIsCompleteFilePath compositionData:(CompositionData*)compositionThisFileBelongsTo
| loadedFilePath | The local file path of the downloaded file |
| - (void) didReceiveCategoryArray: | (NSArray *) | categoryArray | [implementation] |
Implementation of MediaWikiCategoryQueryDelegate method.
Receives the read category content chunk and appends it into the target mutable array, unless a stop was requested, in which case the worker object will stop working.
If the query object indicates that there are more category chunks available, a new read operation continuing from the continue point given by the ISMLP query API will be started automatically. Once all chunks have been read, a message will be sent to the target object defined in the static factory method call to the selector defined also therein. The selector has a signature of (void)methodName:(NSArray*)readCategoryNamesAsNSStrings
| categoryArray | Array read by the MediaWikiCategoryQuery XML parser |
| - (void) didReceiveCompositionData: | (id) | compData | [implementation] |
Implementation of MediaWikiPageQueryDelegate method.
Reports the read composition data (ie. an IMSLPCompositionData object) to the target object and method defined by the factory method call which started the read operation. The selector has a signature of (void)methodName:(CompositionData*)cData
| compData | The composition's data read by a MediaWikiPageQuery object |
| + (float) downloadProgressFor: | (NSString*) | fileName |
Returns a value between 0.0 and 1.0 describing the download progress for the given file name.
Checks whether a download is in progress for the given file name, and returns a value between 0.0 and 1.0 depending on the amount of bytes received. Returns -1.0 if there is no file download in progress for the given filename, and some large negative number if the download doesn't know the expected size of the file.
| - (float) getDownloadProgress |
An IMSLPQueryHelper worker object instance method to report the current download progress of a file.
A helper method for [IMLSPQueryHelper downloadProgressFor:fileName]. Returns the download progress ratio between received bytes and expected bytes as a float between 0.0 and 1.0, -1.0 if no file download is in progress for this worker object, and a rather large negative number if the download doesn't know how many bytes to expect.
| + (NSString *) imslpAPIURL |
Static method returning the current IMSLP API url.
| + (NSString *) imslpFetchURL |
Static method returning the current IMSLP page fetch URL.
| + (NSString *) imslpFileURL |
Static method returning the current IMSLP file download URL.
| + (void) initialize | [implementation] |
Initializes the class.
Initializes the class and sets the default IMSLP API URL, page fetch URL and file download URL.
| - (id) initWithCategory: | (NSString*) | category | |
| intoArray: | (NSMutableArray *) | mutableArray | |
init method for the IMSLPQueryHelper worker object.
Not to be called directly from outside the class!
This method initializes a worker category read object used by IMSLPQueryHelper. It is not intended to be used directly, instantiation and initialization should happen through the static class methods.
| category | The category to read |
| mutableArray | The NSMutableArray that will receive the read category contents. |
| - (id) initWithTitle: | (NSString*) | pTitle |
init method for the IMSLPQueryHelper worker object.
Not to be called directly from outside the class!
This method initializes a worker page or file read object used by IMSLPQueryHelper. It is not intended to be used directly, instantiation and initialization should happen through the static class methods.
| pTitle | The page title or filename for the target of this operation. |
| - (void) progressUpdate: | (id) | from | [implementation] |
Implementation of the MediaWikiProgressListener method.
Receives periodic status updates from MediaWikiQuery / MediaWikiDownload objects.
| from | The MediaWikiQuery or MediaWikiDownload object reporting the read bytes status update. |
| + (int) queryStatusFor: | (NSString*) | destination |
Returns a more detailed query status against the given destination.
The destination is the same string (not necessarily the same string object, just equivalent) used to start the category/page/file/download query.
| + (BOOL) readIMSLPCategory: | (NSString *) | categoryName | |
| reportTo: | (id) | targetObj | |
| withMethod: | (SEL) | targetMethod | |
[implementation] |
Begin reading a category from IMSLP, writing the results into an array and report progress to the defined target object and method.
The static method begins an automatic read/XML parse process which reads the named category into a private NSMutableArray. Once the read process is completed, it will send a copy of the array as a parameter to the given object and method. The helper reports errors using the CatNiPErrorManager.
Remember that categories always start with "Category:" querying the compositions of "Bach, Johann Sebastian" is done with the categoryName "Category:Bach, Johann Sebastian". You need to prepend "Category:" yourself, the helper won't do it for you!
| categoryName | The *full name* of the category to be read from IMSLP |
| targetObj | The object which will receive progress reports (and error messages later) |
| targetMethod | A selector describing the method which will be called to report progress (signature: (void)name:(id)msg, where msg is nil when a category has been partially read and a NSArray containing the category results when the read has completed. Later on it might also be a NSError* describing any error encountered. |
| + (BOOL) readIMSLPFile: | (NSString *) | fileName | |
| ofComposition: | (CompositionData*) | theCompo | |
| reportTo: | (id) | targetObj | |
| withMethod: | (SEL) | targetMethod | |
A factory method for downloading a file from IMSLP to local storage.
Starts an asynchronous reading process which will download the given composition score file from IMSLP to local storage. Once completed succesfully, the given object will be called in the given method with parameters describing both the local storage path of the file and the original filename.
The progress of the file download can be queried using the [IMSLPQueryHelper downloadProgressFor:fileName] static method.
| fileName | The IMSLP music score to download |
| ofComposition | The composition data object that represents which composition the loaded score belongs to |
| reportTo | Object which should receive the download completion message |
| targetMethod | Method to call after downloading is complete. The signature for the method should be -(void)loadReport:(id)filePathArray :(id)compositionData . The first parameter is a 2-element array with the original filename at index 0 and the path it was loaded to at index 1, the second parameter is the composition data passed to this factory method. |
| + (BOOL) readIMSLPPage: | (NSString *) | pageName | |
| composerName: | (NSString *) | cName | |
| reportTo: | (id) | targetObj | |
| withMethod: | (SEL) | targetMethod | |
Read a IMSLP (composition) wiki page parsing composition music scores into an IMSLPCompositionData object and report it to the object and method given.
The operation will be done asynchronously, and the factory method will return immediately with a value telling whether the read operation was started or not. Read operations against compositions which are already ongoing will not be started.
| pageName | The full composition name as reported by IMSLP |
| composerName | The composer name (as reported by IMSLP, except without the "Category:" bit) |
| reportTo | The object which should receive the read composition data |
| withMethod | The method which should be called to receive the data. The method should have a signature of -(void)name:(id)imslpObject, the imslpObject will be of type CompositionData. |
| + (BOOL) readInProgressFor: | (NSString*) | destination |
Checks whether there is an active read operation against the given destination.
The destination is the same string (not necessarily the same string object, just equivalent) used to start the category/page/file download query.
| + (void) setImslpAPIURL: | (NSString*) | newUrl |
Static method to set the IMSLP API URL.
Copies the given string.
Used to set the IMSLP full API URL (without the '?' signifying GET parameter list start), eg. [IMSLPQueryHelper setImslpAPIURL:"http://www.imslp.org/api.php"];
| newUrl | The new URL pointing to the IMSLP API |
| + (void) setImslpFetchURL: | (NSString*) | newUrl |
Static method to set the ISMLP page fetch URL.
Copies the given string.
Used to set the ISMLP page fetch URL (without the '?' signifying GET parameter list start). eg. [IMSLPQueryHelper setImslpFetchURL:"http://www.imslp.org/index.php"];
| newUrl | The new URL pointing to the ISMLP page display service |
| + (void) setImslpFileURL: | (NSString*) | newUrl |
Static method to set the IMSLP file download URL.
Copies the given string.
Used to set the IMSLP file download URL (this time WITH the '?' GET parameter start character, if required). The filename is appended to this URL.
| newUrl | The new URL pointing to the IMSLP file download service |
| - (void) startCategoryFetch |
Starts the category query encapsulated by this worker object.
Builds a MediaWikiCategoryQuery object and starts the query.
| - (void) startDownload |
The starting point method for file download work.
Requires that the pageTitle property, targetObject property and targetMethod property are set for succesful completion.
| - (void) startPageFetch |
Starts the page (composition data) read operation.
Requires that the pageTitle, composerName, targetObject and targetMethod properties are set for the work to complete succesfully.
- (NSString*) categoryName [read, write, copy] |
The full MediaWiki category name for a category contents query.
- (NSString*) composerName [read, write, copy] |
The composer name for composer "contents" queries in IMSLP.
- (NSString*) pageTitle [read, write, copy] |
The page title for composition score list queries.
- (int) queryStatus [read, write, assign] |
A more detailed query status property, uses the local enum MWStatus.
- (BOOL) stopRequested [read, write, assign] |
A simple flag telling the worker object whether it should stop working.
- (NSMutableArray*) targetArray [read, write, retain] |
The array into which category contents are read.
- (SEL) targetMethod [read, write, assign] |
The method signature describing to which method in the target object the helper should send progress reports to.
The signature that targetMethod needs to have depends on the factory method called
- (id) targetObject [read, write, retain] |
The target object which shall receive progress reports by calling the specified targetMethod.
- (CompositionData*) thisComposition [read, write, retain] |
Composition data retained so that it can be given back to the read requester upon completion.
- (BOOL) working [read, write, assign] |
A simple flag telling whether the worker object is working or not.
1.7.4 
