001 /*
002 * Created by IntelliJ IDEA.
003 * User: d@hd.org
004 * Date: 10-Jul-02
005 * Time: 11:17:04
006
007 Copyright (c) 1996-2011, Damon Hart-Davis
008 All rights reserved.
009
010 Redistribution and use in source and binary forms, with or without
011 modification, are permitted provided that the following conditions are
012 met:
013
014 * Redistributions of source code must retain the above copyright
015 notice, this list of conditions and the following disclaimer.
016
017 * Redistributions in binary form must reproduce the above copyright
018 notice, this list of conditions and the following disclaimer in the
019 documentation and/or other materials provided with the
020 distribution.
021
022 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
023 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
024 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
025 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
026 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
027 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
028 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
029 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
030 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
031 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
032 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
033
034 */
035 package org.hd.d.pg2k.webSvr.ads;
036
037 import java.util.Locale;
038 import java.util.Random;
039
040 /**This is the interface of all AdBean advertising beans.
041 * Beans to support advertising in the body of a page
042 * are put in the classpath and loaded by name, and must
043 * implement this interface.
044 * <p>
045 * An AdBean can produce several sorts of output, the usual
046 * one being some well-behaved HTML to insert into a page as
047 * a banner or elsewhere.
048 * <p>
049 * AdBean entities should be completely thread-safe and should
050 * probably not carry significant state from call to call.
051 * <p>
052 * AdBean items can signal their affinity to certain Gallery
053 * topic areas or keywords or even exhibit prefixes and may
054 * be used preferentially around such exhibits.
055 * <p>
056 * When asked to produce output, this is passed a random-number
057 * source to help generate its output. A bean should assume that
058 * the source is a shared resource (eg that is should not be locked
059 * for long periods) and that it <em>may</em> be expensive to use
060 * and so using it sparingly is a good thing.
061 * <p>
062 * Many of the routines take an immutable Context argument, which details
063 * which Gallery section and/or exhibit is featured near the ad
064 * insert, if appropriate, and what is the preferred user locale.
065 * <p>
066 * <strong>This interface and its subcomponents must not depend on any PG2K
067 * types/classes, because it must be possible to take this file/class
068 * on its own and compile against it.</strong>
069 */
070 public interface AdBeanInterface
071 {
072 /**Details context in which advertisement is to be shown.
073 * Is immutable for thread-safety, etc.
074 * <p>
075 * Context items may be null, indicating that they are not
076 * applicable to this particular context,
077 * but any items that are non-null must be mutually consistent.
078 * <p>
079 * A generation routine is generally free to ignore all of the
080 * supplied data if it wishes to.
081 */
082 public static final class Context
083 {
084 /**Construct a complete context.
085 * Items that do not apply can be null.
086 * Any that are non-null must be consistent with one another
087 *
088 * @param loc if non-null, the preferred locale
089 * @param section if non-null, the appropriate top-level Gallery section
090 * @param exhibitName if non-null, is the full name of the specific exhibit associated with this page
091 */
092 public Context(final Locale loc, final String section, final String exhibitName)
093 {
094 locale = loc;
095 gallerySection = section;
096 exhibit = exhibitName;
097
098 if((gallerySection != null) && (exhibit != null))
099 {
100 if(!exhibitName.startsWith(gallerySection + '/'))
101 { throw new IllegalArgumentException("inconsistent arguments"); }
102 }
103 }
104
105 /**The Locale of the visitor, or null.
106 * Assumed immutable, so handed out directly without a copy being
107 * taken (nor a copy made on construction).
108 */
109 private final Locale locale; // Assumed immutable.
110
111 /**The gallery section (top-level directory, or null.
112 * If not null and exhibit is non-null, must be the directory in exhibit.
113 */
114 private final String gallerySection;
115
116 /**The immutable details of the exhibit close to this ad, or null. */
117 private final String exhibit;
118
119 /**Get the locale of the visitor, or null if none specified or relevant. */
120 public Locale getLocale() { return(locale); }
121
122 /**Get the gallery section (top-level directory) for this ad, or null if none relevant.
123 * If non-null and the exhibit is non-null, these two will be consistent.
124 */
125 public String getGallerySection() { return(gallerySection); }
126
127 /**Get the full name of the exhibit connected with this ad, or null if none relevant.
128 * If non-null and the exhibit is non-null, these two will be consistent.
129 */
130 public String getExhibit() { return(exhibit); }
131 }
132
133 /**Can be used to set general parameters for the bean, or can be null.
134 * It is up to the bean how or if to interpret this value at all.
135 *
136 * @return instance so as to allow pure expression constructions of form
137 * (new ...Bean()).setParams().getHTMLBodyInsert(xxx, rnd)
138 */
139 public AdBeanInterface setParams(String rawParams);
140
141 /**Can make an HTML body-text insert in the given context.
142 */
143 public boolean canMakeHTMLBodyInsert(Context ctxt);
144
145 /**Make HTML body text in the given context, or null if none can be made.
146 * This takes a random-number source and the user's locale
147 * and generates a segment of HTML to insert into a page.
148 * <p>
149 * Returns the empty string if not possible.
150 */
151 public String getHTMLBodyInsert(Context ctxt, Random source);
152 }