Setting up ERMailer application
Contributed by Max Muller to Project Wonder,
ERMailer is a simple application that sits on top of ERCoreBusinessLogic that
can deliver email saved into a database. It uses the ERJavaMail for the actual
sending of email. Once set up, your application will simply create mail
enterprise objects, set the attributes and save the mail entities. The ERMailer
app will independently send mail using the data from the same database,
providing the convenience of having one central mailing agent for all your WO
apps that handles mail archiving, mailing errors and retires automatically. Here
are instructions on how I set it up....
Update 01/15/2007: These
instructions are no longer valid for latest WOnder frameworks.
ERCoreBusinessLogic has changed significantly since these instructions were
originally created. I have just created my own simpler email database framework
and a simpler mailer
app.
Prerequisites:
Wonder source has been downloaded
ERPrototypes has been setup for your database
Creating the supporting database
The introduction comment is taken from the README.txt in the Wonder source directory (you have downloaded and built Wonder from CVS on sourceforge already, haven't you?). It gives us a clue that you can find the EOModel in the ERCoreBusinessLogic framework.
So the first step is to create the database corresponding to the model.
Assuming you are working on localhost in development and using MySQL, create an empty database named "ercore" on your MySQL server.
Open the ERCoreBusinessLogic framework project:
~/Wonder/Common/Frameworks/ERCoreBusinessLogic/ERCoreBusinessLogic.pbproj
Patches (required on Dec 28, 2006 CVS source)
Before opening any eomodel, make sure your framework references are valid (not red font in XCode)
Next, double-click the ERMail.eomodeld file that's inside the Resources group of the project.
Before proceeding any further, check that the following entity/fields are all configured to use the 'boolean' prototype which has VARCHAR width 5 as the external type. If they are using intBoolean, I recommend you change them to 'boolean' prototype because, with WO 5.2.3, you will probably have Class cast Exceptions otherwise in the Project Wonder code. If you do change these attributes and the text in the 'Column' column turns brown in color, then cut the 'Column' text, click on another row, and then go back to that field and re-paste the column name so that the text color turns black. This overcomes a current EOModeler bug which will manifest itself in the 'Column' field being missing for that attribute when you run the app.
ERCMailMessage/contentGzipped
ERCMailMessage/shouldArchiveSentMail
ERCMailMessageArchive/contextGzipped
ERCMailMessageArchive/shouldArchiveSentMail
Now save the EOModel so the boolean changes take effect.
Set the adaptor info (requires table creation privileges .... I use mysql root user temporarily for this) for your "ercore" database using , but DO NOT save the eomodel with your adaptor info. We can set the adaptor info in app Properties later.
Create your database schema by selecting the ERCoreBusinessLogic icon and using the sql button in the toolbar. For SQL options in MySQL, check only "Create Tables", "Primary Key Constraints" and "Create Primary Key Support".
Verify that your DB got generated correctly if you wish.
Close the EOModel without saving.
Next navigate to the ERCoreBusinessLogic directory and delete the backup EOModel file ending in a tilde (~) named "ERCoreBusinessLogic.eomodeld~". If you don't this may cause problems later in deployment.
Now open mysql command line client and create a user/password for select, insert, create, delete privileges that apps using ERCoreBusinessLogic will need for connecting to the database, for example
mysql> grant select, insert, update, delete on ercore.* to ercore_app@'192.%' identified by 'password_for_ercore_app', ercore_app@localhost identified by 'password_for_ercore_app';
Configuring ERMailer.woa
Now configure the Properties in ERMailer something like this:
## We want to use the mail facility
ERCUseMailFacility = true
# This value is in seconds
er.javamail.mailer.ERBatchMailerDaemonFrequency = 60
# If you want to test creating a test email in the database and sending it, set
# this flag to true
er.javamail.mailer.ERTestSendingMail=true
# ERCoreBusinessLogic Framework Properties
# These properties are pushed into the Java system properties for
# applications linking against to this framework
# You can override them from the application's Properties file or
# command-line arguments.
# Remove the leading '#' to uncomment a property
#########################################################################
# Common Settings
#########################################################################
# ERCMailState class, by default mail is disabled
er.corebusinesslogic.ERCUseMailFacility = true
# If you are using a database other than MySQL it is highly recommended that
# you have these settings in your WebObjects.properties or your Application properties
# Note that you *should* include the ones that are empty to stomp over any settings
# in the ERCoreBusinessLogic.eomodeld
ERCoreBusinessLogic.URL = jdbc:mysql://db_server/ercore?capitalizeTypenames=true
ERCoreBusinessLogic.DBUser = ercore_app
ERCoreBusinessLogic.DBPassword = <ercore_app user password here>
ERCoreBusinessLogic.DBDriver =
ERCoreBusinessLogic.DBPlugin =
ERCoreBusinessLogic.DBJDBCInfo =
#########################################################################
# Problem Mails
#########################################################################
# If you want to use the Problem Email reporting facility then you need to set these values
er.corebusinesslogic.ERCoreBusinessLogic.ProblemEmailDomain = foo.com
er.corebusinesslogic.ERCoreBusinessLogic.ProblemEmailRecipients = (foo@bar.com, food@bars.com)
#########################################################################
# ERJavaMail settings
#########################################################################
# *** ERJavaMail settings
# *** Defaults to 'safe' settings:
# ***
# Sometimes when sending big masses of emails, the java virtual machine
# doesn't collects correctly the garbage and needs a little delay
# between each message sending. Use this option if you have problem with
# memory management
er.javamail.useSenderDelay = true
# This delay is set to 15 milliseconds
er.javamail.senderDelayMillis = 15
# * Default encoding used for ERJavaMail
er.javamail.defaultEncoding = iso-8859-1
# * Enables ERJavaMail to send all the mails to only one destination
# This is useful when debugging
er.javamail.centralize = false
# * Prints javamail debug infos
# It is recommended to activate this switch when there are problems
# with smtp configuration
er.javamail.debugEnabled = false
# * The admin email, this is where "centralized" mails will go
er.javamail.adminEmail = admin@domain.com
# * SMTP outbound host
er.javamail.smtpHost = smtp.domain.com
# * Number of messages that the sender queue can hold at a time
er.javamail.senderQueue.size = 50
# * Time to wait when mail sender queue is overflowed
er.javamail.milliSecondsWaitIfSenderOverflowed = 6000
# Used to set a default X-Mailer
#er.javamail.mailer.XMailerHeader =
# White and black email address patterns
# This can be useful in testing when say
# you only want to allow emails to be sent to *@mycompany.com
# In this case you would add:
# er.javamail.WhiteListEmailAddressPatterns=("*@mycompany.com", "somebody@mac.com")
# To prevent sending mail to certain addresses you can use the black list
# er.javamail.BlackListEmailAddressPatterns=("*@baddomain.com", "badperson@mycompany.com")
WOSMTPHost=smtp.domain.com
#########################################################################
# ERXLogger
#########################################################################
# Pattern codes:
# %-5p : Priority DEBUG, INFO, WARN, etc.
# %d(ISO08601 : Date and time
# %t : Thread
# %c : Logger name (usually a class name)
# %m%n : Log message arguments
# Available levels are DEBUG, INFO, WARN, ERROR, FATAL
# log4j appender and formatting
log4j.rootLogger=WARN, A2
log4j.loggerFactory=er.extensions.ERXLogger$Factory
# A2 is a DailyRollingFileAppender
log4j.appender.A2=org.apache.log4j.DailyRollingFileAppender
log4j.appender.A2.file=/tmp/log4j_ERMailer.log
log4j.appender.A2.datePattern='.'yyyy-MM-dd
log4j.appender.A2.append=true
log4j.appender.A2.layout=org.apache.log4j.PatternLayout
log4j.appender.A2.layout.ConversionPattern=%-5p %d{ISO8601} [%t] (%c) - %m%n
# ----- end of Properties file -----------
For deployment, you need to fix the ERMailer framework references to point to the install location, not the user's location. If you fail to do this the MacOSClassPath.txt file inside the ERMailer.woa bundle will be incorrect and it will contain references to the built frameworks in ~/Roots which probably will not exist on your server.
Do do this, just select each of the five ERxxxxxx.framework 'toolbox' icons in turn in the Frameworks group in the ERMailer project. For each one, click the Info button in the toolbar and use the Choose button to select the framework path in its installed location which should be /Library/Frameworks.
Alternatively, just edit the MacOSClassPath.txt file by hand in the built .woa bundle which is what I did the first time I deployed ERMailer.woa.
Rebuild and reinstall Project Wonder
When your app is copied over to the deployment server, make sure you do chmod and chown to apply correct owner and permissions to the ERMailer.woa package and all its recursive contents.
[Feedback is welcome: kieran_lists @ mac dot com]
Prerequisites:
Wonder source has been downloaded
ERPrototypes has been setup for your database
Creating the supporting database
The introduction comment is taken from the README.txt in the Wonder source directory (you have downloaded and built Wonder from CVS on sourceforge already, haven't you?). It gives us a clue that you can find the EOModel in the ERCoreBusinessLogic framework.
So the first step is to create the database corresponding to the model.
Assuming you are working on localhost in development and using MySQL, create an empty database named "ercore" on your MySQL server.
Open the ERCoreBusinessLogic framework project:
~/Wonder/Common/Frameworks/ERCoreBusinessLogic/ERCoreBusinessLogic.pbproj
Patches (required on Dec 28, 2006 CVS source)
Before opening any eomodel, make sure your framework references are valid (not red font in XCode)
Next, double-click the ERMail.eomodeld file that's inside the Resources group of the project.
Before proceeding any further, check that the following entity/fields are all configured to use the 'boolean' prototype which has VARCHAR width 5 as the external type. If they are using intBoolean, I recommend you change them to 'boolean' prototype because, with WO 5.2.3, you will probably have Class cast Exceptions otherwise in the Project Wonder code. If you do change these attributes and the text in the 'Column' column turns brown in color, then cut the 'Column' text, click on another row, and then go back to that field and re-paste the column name so that the text color turns black. This overcomes a current EOModeler bug which will manifest itself in the 'Column' field being missing for that attribute when you run the app.
ERCMailMessage/contentGzipped
ERCMailMessage/shouldArchiveSentMail
ERCMailMessageArchive/contextGzipped
ERCMailMessageArchive/shouldArchiveSentMail
Now save the EOModel so the boolean changes take effect.
Set the adaptor info (requires table creation privileges .... I use mysql root user temporarily for this) for your "ercore" database using , but DO NOT save the eomodel with your adaptor info. We can set the adaptor info in app Properties later.
Create your database schema by selecting the ERCoreBusinessLogic icon and using the sql button in the toolbar. For SQL options in MySQL, check only "Create Tables", "Primary Key Constraints" and "Create Primary Key Support".
Verify that your DB got generated correctly if you wish.
Close the EOModel without saving.
Next navigate to the ERCoreBusinessLogic directory and delete the backup EOModel file ending in a tilde (~) named "ERCoreBusinessLogic.eomodeld~". If you don't this may cause problems later in deployment.
Now open mysql command line client and create a user/password for select, insert, create, delete privileges that apps using ERCoreBusinessLogic will need for connecting to the database, for example
mysql> grant select, insert, update, delete on ercore.* to ercore_app@'192.%' identified by 'password_for_ercore_app', ercore_app@localhost identified by 'password_for_ercore_app';
Configuring ERMailer.woa
Now configure the Properties in ERMailer something like this:
## We want to use the mail facility
ERCUseMailFacility = true
# This value is in seconds
er.javamail.mailer.ERBatchMailerDaemonFrequency = 60
# If you want to test creating a test email in the database and sending it, set
# this flag to true
er.javamail.mailer.ERTestSendingMail=true
# ERCoreBusinessLogic Framework Properties
# These properties are pushed into the Java system properties for
# applications linking against to this framework
# You can override them from the application's Properties file or
# command-line arguments.
# Remove the leading '#' to uncomment a property
#########################################################################
# Common Settings
#########################################################################
# ERCMailState class, by default mail is disabled
er.corebusinesslogic.ERCUseMailFacility = true
# If you are using a database other than MySQL it is highly recommended that
# you have these settings in your WebObjects.properties or your Application properties
# Note that you *should* include the ones that are empty to stomp over any settings
# in the ERCoreBusinessLogic.eomodeld
ERCoreBusinessLogic.URL = jdbc:mysql://db_server/ercore?capitalizeTypenames=true
ERCoreBusinessLogic.DBUser = ercore_app
ERCoreBusinessLogic.DBPassword = <ercore_app user password here>
ERCoreBusinessLogic.DBDriver =
ERCoreBusinessLogic.DBPlugin =
ERCoreBusinessLogic.DBJDBCInfo =
#########################################################################
# Problem Mails
#########################################################################
# If you want to use the Problem Email reporting facility then you need to set these values
er.corebusinesslogic.ERCoreBusinessLogic.ProblemEmailDomain = foo.com
er.corebusinesslogic.ERCoreBusinessLogic.ProblemEmailRecipients = (foo@bar.com, food@bars.com)
#########################################################################
# ERJavaMail settings
#########################################################################
# *** ERJavaMail settings
# *** Defaults to 'safe' settings:
# ***
# Sometimes when sending big masses of emails, the java virtual machine
# doesn't collects correctly the garbage and needs a little delay
# between each message sending. Use this option if you have problem with
# memory management
er.javamail.useSenderDelay = true
# This delay is set to 15 milliseconds
er.javamail.senderDelayMillis = 15
# * Default encoding used for ERJavaMail
er.javamail.defaultEncoding = iso-8859-1
# * Enables ERJavaMail to send all the mails to only one destination
# This is useful when debugging
er.javamail.centralize = false
# * Prints javamail debug infos
# It is recommended to activate this switch when there are problems
# with smtp configuration
er.javamail.debugEnabled = false
# * The admin email, this is where "centralized" mails will go
er.javamail.adminEmail = admin@domain.com
# * SMTP outbound host
er.javamail.smtpHost = smtp.domain.com
# * Number of messages that the sender queue can hold at a time
er.javamail.senderQueue.size = 50
# * Time to wait when mail sender queue is overflowed
er.javamail.milliSecondsWaitIfSenderOverflowed = 6000
# Used to set a default X-Mailer
#er.javamail.mailer.XMailerHeader =
# White and black email address patterns
# This can be useful in testing when say
# you only want to allow emails to be sent to *@mycompany.com
# In this case you would add:
# er.javamail.WhiteListEmailAddressPatterns=("*@mycompany.com", "somebody@mac.com")
# To prevent sending mail to certain addresses you can use the black list
# er.javamail.BlackListEmailAddressPatterns=("*@baddomain.com", "badperson@mycompany.com")
WOSMTPHost=smtp.domain.com
#########################################################################
# ERXLogger
#########################################################################
# Pattern codes:
# %-5p : Priority DEBUG, INFO, WARN, etc.
# %d(ISO08601 : Date and time
# %t : Thread
# %c : Logger name (usually a class name)
# %m%n : Log message arguments
# Available levels are DEBUG, INFO, WARN, ERROR, FATAL
# log4j appender and formatting
log4j.rootLogger=WARN, A2
log4j.loggerFactory=er.extensions.ERXLogger$Factory
# A2 is a DailyRollingFileAppender
log4j.appender.A2=org.apache.log4j.DailyRollingFileAppender
log4j.appender.A2.file=/tmp/log4j_ERMailer.log
log4j.appender.A2.datePattern='.'yyyy-MM-dd
log4j.appender.A2.append=true
log4j.appender.A2.layout=org.apache.log4j.PatternLayout
log4j.appender.A2.layout.ConversionPattern=%-5p %d{ISO8601} [%t] (%c) - %m%n
# ----- end of Properties file -----------
For deployment, you need to fix the ERMailer framework references to point to the install location, not the user's location. If you fail to do this the MacOSClassPath.txt file inside the ERMailer.woa bundle will be incorrect and it will contain references to the built frameworks in ~/Roots which probably will not exist on your server.
Do do this, just select each of the five ERxxxxxx.framework 'toolbox' icons in turn in the Frameworks group in the ERMailer project. For each one, click the Info button in the toolbar and use the Choose button to select the framework path in its installed location which should be /Library/Frameworks.
Alternatively, just edit the MacOSClassPath.txt file by hand in the built .woa bundle which is what I did the first time I deployed ERMailer.woa.
Rebuild and reinstall Project Wonder
When your app is copied over to the deployment server, make sure you do chmod and chown to apply correct owner and permissions to the ERMailer.woa package and all its recursive contents.
[Feedback is welcome: kieran_lists @ mac dot com]
Posted: Friday - July 29, 2005 at 11:13 AM
Quick Links
Statistics
Total entries in this blog:
Total entries in this category:
Published On: Dec 29, 2008 02:27 PM
Total entries in this category:
Published On: Dec 29, 2008 02:27 PM