APT from Yahoo! Java SDK

The Java SDK for APT from Yahoo! API makes it easy to build Search Marketing tools to access and manage APT accounts. Without any pre-knowledge of Axis or SOAP, you can access the APT Web Services as easy as normal Java classes.

Introduction
Build Instructions
Usage Instructions

SDK Configuration
Authentication
Logging
Property File

Documentation
Sample Code

Introduction

The Java SDK for APT from Yahoo! API makes it easy to build Search Marketing tools with Java to programmatically access and manage APT accounts. The aim of the SDK is to encapsulate all APT Web Service logic such that the usage of the APT Web Services becomes as easy as normal Java classes, without any pre-knowledge of Axis or SOAP. The client library is provided in a single jar file that contains all the pre-compiled Axis stub classes and a service factory class to be used to write Java clients accessing the APT Web Services.

To use the Java client library, extract ysm-apt-jsdk jar (i.e. ysm-apt-jsdk-vx.x.x.jar) from the source or binary zip file (i.e. ysm-apt-jsdk-vx.x.x-src.zip or ysm-apt-jsdk-vx.x.x-bin.zip). Put the jar file in your classpath. Create the config and logging folder structure. Create the property files with required values. You don't need to put any other additional libraries in your classpath or do any pre-compiling. You don't need to worry about accessing the WSDL for the web services; the Axis generated stub classes in the client library do it for you.

The SDK comprises of a Factory class, a Constants class, a Log Helper class and a Data Structure for encapsulating the credentials besides Axis client side stubs generated by Axis' WSDL2Java tool. Users can configure the settings using a properties file and programmatically access the APT Web Services API using the ServiceFactory.java class and Axis client stubs.

Build Instructions

Download and install ant if you don't already have it installed
Set ANT_HOME to in your system's environment variables
Set PATH to \bin in your system's environment variables
Ensure JAVA_HOME is set in the system environment variables
Ensure 'tools.jar' is in the classpath entry in the system environment variables
Unzip source zip file, i.e. ysm-apt-jsdk-src-vx.x.x.zip
Open command prompt in project folder
Key 'ant' at command prompt and hit enter
Pick up jar file from build folder and use it as ysm sdk library in client applications following the Usage Instructions
Pick up zip file from the dist directory as needed to distribute project.

Usage Instructions

SDK Configuration

Put ysm-apt-jsdk jar file in the lib folder and reference in your classpath.

Default Settings

ysm-apt-jsdk jar includes a properties file “YahooMarketing.properties” which is treated as the default settings for the SDK. You may overwrite these default settings by providing a custom properties file if needed.
Create a folder "logs" for the output log file. By default, log messages are created in the log file named YahooSM.log. The default log settings are in the properties file “YahooMarketing.properties”. You may also overwrite them to your own log folder and log file.

Custom Settings

Alternatively you can pass in the properties file and log config file path and name as a System property.

System Property name Sample Property value

================== ==================

YAHOO_PROPERTIES_FILE "ConfigDir" + File.separatorChar +"YSM.propperties"

YAHOO_LOG_CONFIG_FILE "ConfigDir" + File.separatorChar +"log4j.propperties"

## Create a ServiceFactory object, loading the configuration files from system property
import com.yahoo.marketing.apt.client.ServiceFactory;

ServiceFactory factory = new ServiceFactory();

//Get a SiteService object from the ServiceFactory
SiteService siteService = factory.getService("SiteService");
// Get a Site object through SiteService
long siteID = 123456;
Site site = siteService.getSite(siteID);

If the above system properties are not found the SDK will use the default settings specified earlier. For settings that are not found in the custom properties file, the default settings will be used.
Specify the logging file name and path in your log config file and ensure the directory structure is created.

Besides, you can also pass the properties file and log config file directly:

## Create a ServiceFactory object, loading the configuration files directly
import com.yahoo.marketing.apt.client.ServiceFactory;

String configFile = "/myConf/myConfig.properties";
String logConfigFile = "/myConf/myAPTClientLogConfig.properties";

ServiceFactory factory = new ServiceFactory(configFile, logConfigFile);

//Get a SiteService object from the ServiceFactory
SiteService siteService = factory.getService("SiteService");
// Get a Site object through SiteService
long siteID = 123456;

Authentication

To access APT from Yahoo! Web Service API, a set of credential information must be provided. There are two ways to pass the credentials to the SDK.

Pass credentials directly in the code.

Credential credential = new Credential("username", "password", "apt-api-license-key", "123465789");

String configFile = "/myConf/myConfig.properties";
String logConfigFile = "/myConf/myLogConfig.properties";

ServiceFactory factory = new ServiceFactory(credential, configFile, logConfigFile);

//Get a SiteService object from the ServiceFactory
SiteService siteService = factory.getService(SiteService.class);
// Get a Site object through SiteService
long siteID = 123456;
Site site = siteService.getSite(siteID);

Put credential information together with other settings in the properties file.

In the properties file "myConfig.properties":

## Location Cache Filename and expiration settings
Location.Cache.Filepath.Prefix=YahooAPT_LocCache_
Location.Cache.Expiration.Millis=86400000
# 24hrs - 86400000 ; 1min - 60000 ; 5min - 300000

## APT Endpoint and Location settings
APT.Version=V1
APT.Endpoint=https://sandbox.apt.yahooapis.com/

## APT Credentials
APT.Username=username
APT.Password=password
APT.License=apt-api-license-key
APT.AccountID=123456789

In the class main method:

String configFile = "/myConf/myConfig.properties";
String logConfigFile = "/myConf/myLogConfig.properties";

ServiceFactory factory = new ServiceFactory(credential, configFile, logConfigFile);

//Get a SiteService object from the ServiceFactory
SiteService siteService = factory.getService(SiteService.class);
// Get a Site object through SiteService
long siteID = 123456;
Site site = siteService.getSite(siteID);

Logging

The APT SDK uses ServiceLog class to implement logging throughout the code. To enable the logging, put the logging configurations in log config file and set APT.Log.EnableLog into true.

#################################
###APT Log Properties ###
#################################
APT.Log.EnableLog=true
APT.Log.LogSOAPMessages=false

##################################
### Commons-logging Properties ###
##################################

# Directly selects log4j logging implementation class.
org.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.Log4jFactory

# Maps to a Log4J category (uses log4j.properties)
#  note: org.apache.log4j.Category is deprecated in favor of org.apache.log4j.Logger
#  and requests for a Category object will return a Logger object.
org.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JCategoryLog

########################
### Log4J Properties ###
########################

# Set root category priority to INFO and its appender to CONSOLE and LOGFILE
log4j.rootCategory=FATAL, CONSOLE, LOGFILE

# Set the APT service logger category to INFO
log4j.logger.com.yahoo.marketing.apt=INFO

# CONSOLE is set to be a ConsoleAppender using a PatternLayout.
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.Threshold=DEBUG
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%d{HH:mm:ss} %-5p %x %c %m%n
#log4j.appender.CONSOLE.layout.ConversionPattern=%d{HH:mm:ss} - %m%n
#log4j.appender.CONSOLE.layout.ConversionPattern=%d %-4r [%t] %-5p %c %x - %m%n

 # LOGFILE is set to be a File appender using a PatternLayout.  Change log4j.appender.LOGFILE.File to your log filename
log4j.appender.LOGFILE=org.apache.log4j.RollingFileAppender
log4j.appender.LOGFILE.File=logs/YahooSM.log
log4j.appender.LOGFILE.Append=true
log4j.appender.LOGFILE.File.MaxFileSize=1MB
log4j.appender.LOGFILE.File.MaxBackupIndex=30
log4j.appender.LOGFILE.Threshold=INFO
log4j.appender.LOGFILE.layout=org.apache.log4j.PatternLayout
log4j.appender.LOGFILE.layout.ConversionPattern=%d{HH:mm:ss} %-5p %c %m%n

To log SOAP request and response XML messages, set APT.Log.LogSOAPMessages into true. Then in the class main method:

String configFile = "/myConf/myConfig.properties";
String logConfigFile = "/myConf/myLogConfig.properties";

ServiceFactory factory = new ServiceFactory(credential, configFile, logConfigFile);
LogHelper log = factory.getLogHelper();

try {
	// Get a SiteService object from the ServiceFactory
	SiteService siteService = factory.getService(SiteService.class);
	// Get a Site object through SiteService
	long siteID = 123456;
	Site site = siteService.getSite(siteID);

	// Log the success message together with the SOAP request and response message.
	log.info((Stub)siteService, "getSite() has been called successfully.");
} catch(ApiFault fault) {
	// Log the failure message together with the SOAP request and response message.
	log.error((Stub)siteService, "getSite() has failed");
}

Property File

The default property file name is "YahooMarketing.properties" The properties defined in this file are:
ServiceFactory configuration properties:

Location.Cache.Filepath.Prefix
Specifies the relative path and filename prefix for the local location cache file which stores the URL endpoint for each given Account.
Sample Value: YahooAPT_LocCache_
Location.Cache.Expiration.Millis
Specifies the location cache expiration interval in milliseconds.
Sample Value: 86400000
APT.Service.Version
Specifies the APT Web Services Version
Sample Value: V1
APT.Service.Endpoint
Specifies the APT Web Services Endpoint
Sample Value: https://sandbox.apt.yahooapis.com/services
APT.Service.Namespace
Specifies the APT Web Services Namespace
Sample Value: http://apt.yahooapis.com
APT.Service.Endpoint
Specifies the APT Web Services Endpoint
Sample Value: https://sandbox.apt.yahooapis.com/services
APT.Timeout
APT HTTP Timeout setting in minutes - recommended setting is 11 minutes
Sample Value: Non-zero integer values
APT.Username
The assigned username
Sample Value: username
APT.Password
The assigned password
Sample Value: password
APT.License
The license key assigned to the user
Sample Value: apt-api-license-key
APT.AccountID
The assigned AccountID for the account managed by the user
Sample Value: 123456789

Logging Configuration properties:

APT.Log.EnableLog
Whether to enable logging
Sample Value: true
APT.Log.LogSOAPMessage
Whether to enable logging SOAP request and response messages
Sample Value: false
org.apache.commons.logging.LogFactory
The log factory of the logging framework used in your application
Sample Value: org.apache.commons.logging.impl.Log4jFactory
org.apache.commons.logging.Log
The log implementation of the logging framework used in your application
Sample Value: org.apache.commons.logging.impl.Log4JCategoryLog
log4j.logger.com.yahoo.marketing.apt
The APT service logger category
Sample Value: INFO, CONSOLE, LOGFILE

NOTE: By default the logging configuration is specified in the YahooMarketing.properties file. However one can use a separate logging configuration file and pass in the file name directly or as a system property as detailed in the Custom Settings under the SDK Configuration section above.

Documentation

Javadoc
    API documentation generated with javadoc.
License
    The terms of the license used for the SDK.
APT from Yahoo! Home
    Home of APT from Yahoo!
APT from Yahoo! Application Help
    Application Help of APT from Yahoo!.

Sample Code

Please refer the sample code in the example folder of the SDK for usage and best practices for coding using the SDK.

System Property name	Sample Property value
==================	==================
YAHOO_PROPERTIES_FILE	"ConfigDir" + File.separatorChar +"YSM.propperties"
YAHOO_LOG_CONFIG_FILE	"ConfigDir" + File.separatorChar +"log4j.propperties"