 |
CatNiP prefinal
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: |
| 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 category this helper object is reading. | |
| NSString * | composerName |
| Composer name for page queries. | |
| NSString * | pageTitle |
| Composition name or score filename to fetch, depending on which start is used. | |
| int | queryStatus |
| A more detailed query status property, uses the local enum MWStatus. | |
| BOOL | stopRequested |
| Flag indicating whether the helper object has been asked to stop the read process. | |
| NSMutableArray * | targetArray |
| The array into which the helper object reads the data. | |
| 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 |
| Flag indicating whether the helper object is currently working. | |
Private Attributes | |
| MediaWikiCategoryQuery * | myCategoryQuery |
| The MediaWikiCategoryQuery doing the actual work. | |
| MediaWikiDownload * | myDownload |
| The MediaWikiDownload object used for fetching a score file. | |
| MediaWikiPageQuery * | myPageQuery |
| The MediaWikiPageQuery object used for fetching a composition's data. | |
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.
Definition at line 21 of file IMSLPQueryHelper.h.
| - (enum) MWStatus |
Enumerates the different statuses available for IMSLPQueryHelper instances.
| MWQueryNoStatus | |
| MWQueryStarting | |
| MWQueryInProgress | |
| MWQueryCompleted | |
| MWQueryFailed | |
| MWQueryCancelled |
Definition at line 104 of file IMSLPQueryHelper.h.
| + (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.
Definition at line 365 of file IMSLPQueryHelper.m.
References MWQueryCancelled, queryStatus, and stopRequested.
| + (BOOL) abortRead: | (NSString*) | destination |
Aborts the requested read.
Definition at line 346 of file IMSLPQueryHelper.m.
References imslpQueries, MWQueryCancelled, queryStatus, and stopRequested.
| - (void) categoryParseFailed: | (NSError *) | error | [implementation] |
Implementation of MediaWikiCategoryQueryDelegate method.
Receives any XML parse/validation errors encountered by the MediaWikiCategoryQuery
| error | The error encountered. |
Reimplemented from <MediaWikiCategoryQueryDelegate>.
Definition at line 531 of file IMSLPQueryHelper.m.
References MWQueryFailed, CatNiPErrorManager::reportError:, and CatNiPErrorManager::sharedManager.
| - (void) dealloc | [implementation] |
Custom dealloc implementation to release worker objects etc.
Definition at line 631 of file IMSLPQueryHelper.m.
References myCategoryQuery, myDownload, myPageQuery, targetArray, and targetObject.
| - (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 |
Reimplemented from <MediaWikiDownloadDelegate>.
Definition at line 565 of file IMSLPQueryHelper.m.
References MWQueryCompleted, MWQueryFailed, and targetObject.
| - (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 |
Reimplemented from <MediaWikiCategoryQueryDelegate>.
Definition at line 495 of file IMSLPQueryHelper.m.
References MediaWikiCategoryQuery::continueFrom, MWQueryCancelled, MWQueryCompleted, myCategoryQuery, MediaWikiQuery::startQuery, stopRequested, and targetObject.
| - (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 |
Reimplemented from <MediaWikiPageQueryDelegate>.
Definition at line 549 of file IMSLPQueryHelper.m.
References MWQueryCompleted, and targetObject.
| + (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.
Definition at line 329 of file IMSLPQueryHelper.m.
References getDownloadProgress, imslpQueries, and MWQueryNoStatus.
| - (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.
Definition at line 618 of file IMSLPQueryHelper.m.
References myDownload.
| + (NSString *) imslpAPIURL |
Static method returning the current IMSLP API url.
Definition at line 83 of file IMSLPQueryHelper.m.
| + (NSString *) imslpFetchURL |
Static method returning the current IMSLP page fetch URL.
Definition at line 101 of file IMSLPQueryHelper.m.
| + (NSString *) imslpFileURL |
Static method returning the current IMSLP file download URL.
Definition at line 120 of file IMSLPQueryHelper.m.
| + (void) initialize | [implementation] |
Initializes the class.
Initializes the class and sets the default IMSLP API URL, page fetch URL and file download URL.
Definition at line 50 of file IMSLPQueryHelper.m.
References imslpAPIURL, imslpFetchURL, imslpFileURL, and imslpQueries.
| - (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. |
Definition at line 387 of file IMSLPQueryHelper.m.
References MWQueryNoStatus.
| - (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. |
Definition at line 414 of file IMSLPQueryHelper.m.
References MWQueryNoStatus.
| - (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. |
Reimplemented from <MediaWikiProgressListener>.
Definition at line 586 of file IMSLPQueryHelper.m.
References MediaWikiDownload::abortRead, MWQueryCancelled, queryStatus, MediaWikiDownload::removeProgressListener:, and stopRequested.
| + (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.
Definition at line 308 of file IMSLPQueryHelper.m.
References imslpQueries, MWQueryNoStatus, and queryStatus.
| + (BOOL) readIMSLPCategory: | (NSString *) | categoryName | |
| reportTo: | (id) | targetObj | |
| withMethod: | (SEL) | targetMethod | |
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. |
Definition at line 156 of file IMSLPQueryHelper.m.
References categoryName, imslpQueries, MWQueryStarting, queryStatus, startCategoryFetch, stopRequested, targetMethod, targetObject, and working.
| + (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. |
Definition at line 249 of file IMSLPQueryHelper.m.
References imslpQueries, MWQueryStarting, queryStatus, startDownload, stopRequested, targetMethod, targetObject, thisComposition, and working.
| + (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. |
Definition at line 203 of file IMSLPQueryHelper.m.
References composerName, imslpQueries, MWQueryStarting, queryStatus, startPageFetch, stopRequested, targetMethod, targetObject, and working.
| + (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.
Definition at line 287 of file IMSLPQueryHelper.m.
References imslpQueries, stopRequested, and working.
| + (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 |
Definition at line 93 of file IMSLPQueryHelper.m.
References imslpAPIURL.
| + (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 |
Definition at line 112 of file IMSLPQueryHelper.m.
References imslpFetchURL.
| + (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 |
Definition at line 133 of file IMSLPQueryHelper.m.
References imslpFileURL.
| - (void) startCategoryFetch |
Starts the category query encapsulated by this worker object.
Builds a MediaWikiCategoryQuery object and starts the query.
Definition at line 436 of file IMSLPQueryHelper.m.
References MediaWikiQuery::addProgressListener:, MediaWikiCategoryQuery::categoryName, MediaWikiCategoryQuery::chunkSize, imslpAPIURL, MWQueryInProgress, myCategoryQuery, MediaWikiCategoryQuery::newCategoryQuery:delegate:, and MediaWikiQuery::startQuery.
| - (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.
Definition at line 471 of file IMSLPQueryHelper.m.
References MediaWikiDownload::addProgressListener:, MediaWikiDownload::mediaWikiFilename, MWQueryInProgress, myDownload, and MediaWikiDownload::startQuery.
| - (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.
Definition at line 454 of file IMSLPQueryHelper.m.
References MediaWikiQuery::addProgressListener:, MediaWikiPageQuery::composerName, imslpFetchURL, MWQueryInProgress, myPageQuery, MediaWikiPageQuery::newPageQuery:delegate:, MediaWikiQuery::startQuery, MediaWikiPageQuery::wikiAction, and MediaWikiPageQuery::wikiTitle.
- (MediaWikiCategoryQuery*) myCategoryQuery [private] |
The MediaWikiCategoryQuery doing the actual work.
Definition at line 42 of file IMSLPQueryHelper.h.
- (MediaWikiDownload*) myDownload [private] |
The MediaWikiDownload object used for fetching a score file.
Definition at line 46 of file IMSLPQueryHelper.h.
- (MediaWikiPageQuery*) myPageQuery [private] |
The MediaWikiPageQuery object used for fetching a composition's data.
Definition at line 44 of file IMSLPQueryHelper.h.
- (NSString *) categoryName [read, write, copy] |
The category this helper object is reading.
The full MediaWiki category name for a category contents query.
Definition at line 26 of file IMSLPQueryHelper.h.
- (NSString *) composerName [read, write, copy] |
Composer name for page queries.
The composer name for composer "contents" queries in IMSLP.
Definition at line 30 of file IMSLPQueryHelper.h.
- (NSString *) pageTitle [read, write, copy] |
Composition name or score filename to fetch, depending on which start is used.
The page title for composition score list queries.
Definition at line 33 of file IMSLPQueryHelper.h.
- (int) queryStatus [read, write, assign] |
A more detailed query status property, uses the local enum MWStatus.
Definition at line 35 of file IMSLPQueryHelper.h.
- (BOOL) stopRequested [read, write, assign] |
Flag indicating whether the helper object has been asked to stop the read process.
A simple flag telling the worker object whether it should stop working.
Definition at line 39 of file IMSLPQueryHelper.h.
- (NSMutableArray *) targetArray [read, write, retain] |
The array into which the helper object reads the data.
The array into which category contents are read.
Definition at line 28 of file IMSLPQueryHelper.h.
- (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
Definition at line 92 of file IMSLPQueryHelper.h.
- (id) targetObject [read, write, retain] |
The target object which shall receive progress reports by calling the specified targetMethod.
Definition at line 94 of file IMSLPQueryHelper.h.
- (CompositionData *) thisComposition [read, write, retain] |
Composition data retained so that it can be given back to the read requester upon completion.
Definition at line 34 of file IMSLPQueryHelper.h.
- (BOOL) working [read, write, assign] |
Flag indicating whether the helper object is currently working.
A simple flag telling whether the worker object is working or not.
Definition at line 37 of file IMSLPQueryHelper.h.
1.7.4 
