/*
 Copyright 2010-2016 Warply Inc. All rights reserved.
 
 Redistribution and use in source and binary forms, without modification, 
 are permitted provided that the following conditions are met:
 
 1. Redistributions of source code must retain the above copyright notice, this
 list of conditions and the following disclaimer.
 
 2. Redistributions in binaryform must reproduce the above copyright notice,
 this list of conditions and the following disclaimer in the documentation
 and/or other materials provided with the distribution.
 
 THIS SOFTWARE IS PROVIDED BY THE WARPLY LTD ``AS IS'' AND ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
 EVENT SHALL WARPLY LTD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*!
 @header WLEvent.h
 The WLEvent provides a functional interface for Warply events.
 Use the methods declared here to initialise and create events with arbitrary
 context and type.
 @copyright Warply Inc.
 */
#import <Foundation/Foundation.h>

/*!
 @class WLEvent
 @discussion This class provides methods for creating an event with arbitrary 
 context.
 */
@interface WLEvent : NSObject 
{
@protected
    NSString *_time;
    NSMutableDictionary *_data;
}

/*!
 @methodgroup Class Methods
 @discussion Convinience class methods for initialising an event.
 */
/*!
 @abstract Creates an event.
 @discussion Initializes and returns a newly allocated WLEvent object.
 Initializes and returns a newly allocated WLEvent object.
 @return Returns WLEvent object.
 */
+ (id)event;
/*!
 @abstract Creates an event with arbitrary context.
 @discussion Initializes and returns a newly allocated WLEvent object with the 
 arbitrary context.
 @param context A dictionary object with arbitrary key-value entries.
 @return Returns WLEvent object.
 */
+ (id)eventWithContext:(NSDictionary*)context;

/*!
 @property time
 @abstract A string with event created time in epoch format. Read only property.
 */
@property (nonatomic, readonly) NSString *time;
/*!
 @property data
 @abstract A dictionary with event context. Read only property.
 */
@property (nonatomic, readonly) NSMutableDictionary *data;

/*!
 @methodgroup Initialising Event
 */
/*!
 @abstract Initialise an WLevent object.
 @discussion Initializes and returns a newly allocated WLEvent object with the 
 arbitrary context.
 @param context A dictionary object with arbitrary key-value entries.
 @return Returns WLEvent object.
 */
- (id)initWithContext:(NSDictionary*)context;
/*!
 @methodgroup Getting Event Type
 */
/*!
 @abstract Get event type.
 @discussion This method returns the type of the event.
 @return Returns a string object with event type.
 */
- (NSString *)getType;
/*!
 @methodgroup Adding Context to Event
 */
/*!
 @abstract Add context to event.
 @discussion This method adds a key-value pair to existing context of an event.
 @param value An id object with the value of the key.
 @param key A string object with the key of the value.
 */
- (void)addDataWithValue:(id)value forKey:(NSString*)key;

@end

/*!
 @class WLEventSimple
 @discussion This class provides methods for creating an event with arbitrary
 context and type.
 */
@interface WLEventSimple : WLEvent 
{
@private
    NSString *_type;
}

/*!
 @methodgroup Class Methods
 @discussion Convinience class methods for initialising an event.
 */
/*!
 @abstract Creates an event with arbitrary type.
 @discussion Initializes and returns a newly allocated WLEventSimple object 
 with arbitrary type.
 @param aType A string object with the event type.
 @return Returns WLEvent object.
 */
+ (id)eventWithType:(NSString*)aType;
/*!
 @abstract Creates an event with arbitrary type and context.
 @discussion Initializes and returns a newly allocated WLEventSimple object
 with arbitrary type and context.
 @param aType A string object with the event type.
 @param context A dictionary with arbitrary context.
 @return Returns WLEvent object.
 */
+ (id)eventWithType:(NSString*)aType andContext:(NSDictionary*)context;

/*!
 @methodgroup Initialising Event
 */
/*!
 @abstract Initialise an event with arbitrary type.
 @discussion Initializes and returns a newly allocated WLEvent object with the 
 arbitrary type.
 @param aType A string object with the event type.
 @return Returns WLEvent object.
 */
- (id)initWithType:(NSString*)aType;
/*!
 @abstract Initialise an event with arbitrary type and context.
 @discussion Initializes and returns a newly allocated WLEvent object with the
 arbitrary type and context.
 @param aType A string object with the event type.
 @param context A dictionary with arbitrary context.
 @return Returns WLEvent object.
 */
- (id)initWithType:(NSString*)aType andContext:(NSDictionary*)context;

@end