10Duke
Developer Guide
Contents
Overview
The 10Duke SDK consists of Java class libraries packaged into Java archive (.jar) files. The SDK is specially designed for building Java web applications, but it can also be utilized in desktop, console and mobile applications. In the web application space, the SDK supports developing J2EE Web Applications (.war) as well as using embedded web servers that function as servlet containers.
The 10Duke SDK core class libraries are packaged into a jar file called tenduke-sdk-[version].jar, where [version] is substituted by version number of the SDK package. Core libraries contain the implementation of SDK core features and concepts including media handling, storage, CDN (Content Delivery Network), social media object models, data access and data distribution framework. Features provided by the core libraries allow building rich and versatile social media applications, and the core libraries can be extended for the most advanced use cases.
Developers using the 10Duke SDK can develop their own extensions and/or use extensions provided by 10Duke. The extensions are packaged into separate jar files. One special category of the extensions is called services. Services are additional, independent features for the SDK that are recognized and managed by ServiceManager class.
Core concepts
Runtime lifecycle management
The SDK comes with lifecycle manager that is responsible for initializing the application when the application lifecycle begins (application is started) and cleaning up when the application lifecycle ends (application is closed). Using the lifecycle manager makes it easy for application developers to do necessary initializations to fully utilize the capabilities of the SDK, including core features and extensions.
Built-in lifecycle management classes of the 10Duke SDK include the generic lifecycle manager and specific classes that connect the lifecycle manager to the lifecycle of the environment in which the application is running:
LifecycleManager - Generic lifecycle manager class that is used by specific lifecycle manager implementations (see below). LifecycleManager.beginLifecycle() should be called from the application's main entry point / start sequence, and LifecycleManager.endLifecycle() should be called before application exits.
ServletContextLifecycleManager - Implementation of javax.servlet.ServletContextListener that hooks LifecycleManager to ServletContextListener.contextInitialized() and ServletContextListener.contextDestroyed() calls. ServletContextLifecycleManager can be used as lifecycle manager for web applications, for example by simply configuring it as webapp listener in WEB-INF/web.xml of a web application.
TanukiWrapperLifecycleManager - Implementation of org.tanukisoftware.wrapper.WrapperListener that hooks LifecycleManager to JVM lifecycle managed by Tanuki Java Service Wrapper. Tanuki wrapper and TanukiWrapperLifecycleManager can be used e.g. to build web applications that contain embedded web server / servlet container.
More to study
Usage, see samples
In-depth information, see lifecycle management
See also logging
Object model, data provider and persistence
Object model, data provider and persistence are the cornerstones of most SDK applications. Object model exists to describe real-world concepts. The built-in object model classes are well suited for several domains including the domain of rich social media applications. Object model classes provide a wide set of objects described in a way that suits a wide range of applications. Built-in object model classes are in the package com.tenduke.objectmodel. The object model can also be extended by developers.
Persistence binds object model objects to persistent storage. Provided binding implementation in the package com.tenduke.binding supports binding to popular relational databases including PostgreSQL, MySQL and HSQLDB. Developers can implement bindings for virtually any kind of persistent storage ranging from xml files to large-scale non-relational databases.
Data provider works between object model and binding. Data provider writes to and reads objects from a database, using selected binding implementations. Data provider supports advanced nested read and write operations, making it easy for a developer to access object hierarchies with simple data provider calls. When data provider is used as a gate to access data, it allows sophisticated data management extensions for example; hooking up transparent object caching and integrating to 3rd party systems. Base data provider is in the package com.tenduke.patterns.dataprovider, implementations (currently for JDBC / SQL) in com.tenduke.binding.sql.
The developer can "live" inside the object world without concerns about the complexities of persistence. Data provider implementations, e.g. JdbcDataProvider, provide means to write and query object model samples. An object model sample can consist of a single object, set of objects, or of hierarchical object trees. For domain specific needs, the object model and binding can be extended with much of the persistence infrastructure provided by the SDK classes already.
More to study
Usage, see samples
In-depth information, see object model, object serialization, binding, data provider and data provider management
User management
Main classes that represent the user in the SDK are Account and Profile. Account represents a person or a technical actor in a system. Profile represents a profile in which person or technical actor can interact in the system. Single person (Account) may act in the system via multiple profiles, where each profile may have different profile details, different settings and different privileges. However, the most common case is that there is exactly one Profile for each Account.
User data including user details, roles and permissions are stored in a user database. The user database can be the same single database used for all data stored by the application. In some applications it may be necessary to integrate with existing user databases, authentication interfaces etc. The 10Duke SDK makes it easy to access this kind of external user management databases or interfaces by defining dedicated data provider for user management purposes.
There are several ways how users can be added to the database. Most common approaches include:
- registration, typically implemented as an HTML registration form
- adding users by administrator interface
RegisterUser command is provided for implementing registration.
Authentication and authorization are discussed in the following chapters.
More to study
In-depth information, see user management
Authentication and session management
Authentication is the process of confirming that the user of the system really is who they claim to be. The SDK relies on the Java security framework (in javax.security.auth and its subpackages).
UserManager class provides overloaded login() methods that can be used for authenticating users regardless of how a user interacts with the system. UserManager may be used in the case of authenticating users that interact with the system using HTTP or any other channel provided by the application.
For HTTP clients, SessionServlet provides an endpoint for authenticating users. For successfully authenticated users SessionServlet establishes HTTP session. HTTP session in this context does not refer to HttpSession in javax.servlet.http. Session in this context refers to the semantical meaning of granting a session.
SessionServlet delegates authentication and session management to HTTP session handlers that implement the HttpSessionHandler interface. Existing implementations of HttpSessionHandler include:
CookieBasedHttpSessionHandler is the preferred session handler for end user HTTP sessions. It uses username and password authentication, allowing passing username and password as form or request parameters. After successful authentication a cookie-based distributed session is established. CookieBasedHttpSessionHandler uses internally UserManager for authentication. Implementation of the distributed session supported by CookieBasedHttpSessionHandler is based on digitally signing the session data stored in cookies.
SessionlessBasicAuthHandler and Sessionless10DukeBasicHandler provide only authentication. SessionlessBasicAuthHandler provides standard HTTP basic authentication, Sessionless10DukeBasicHandler provides similar authentication using custom HTTP header. When using these session handlers, authenticated users are handled as if they had a session. Both of these session handlers use internally UserManager for authentication.
ChainedHttpSessionHandler can be used to implement configurable fall-back chain of session handlers.
Developers may extend the set of HttpSessionHandler implementations and develop new authentication and session handling mechanisms.
For username and password based authentication, UserManager allows using the following user data as username:
primary principal of Account
primary email of Account
id of Account
short name of Profile
id of Profile
Under the hood of the implementation of the authentication model defined by Java security framework are LoginModules. LoginModules implement javax.security.auth.spi.LoginModule. Using LoginModules allow changing authentication mechanisms without affecting applications requiring authentication. LoginModules provided by 10Duke SDK include:
LoginModuleForPasswordAuthentication provides username and password based authentication using user database accessed via LOGICAL_DATABASE_USER_MANAGEMENT DataProvider. By default, this DataProvider accesses the basic application database. In effect, default configuration allows user to login simply after user has been added to the database.
Authorization
Authorization is the process of checking permissions to perform an action or access content in the system. The SDK provides role-based authorization model.
Main classes and concepts used for authorization are:
Permission class represents permission that can be granted to user Profiles directly or via Roles
Role class implements role-based authorization
PermissionChecker provides overloaded checkPermission(...) method for performing authorization
Permission and Role are ordinary SDK object model classes that can be used as needed by application. The SDK defines few contracts for using Permissions:
Permissions used to authorize access to object model classes are named by class serialization name. Serialization name is usually the same as the class simple name. For instance, ImageEntry is used as name for Permission controlling access to ImageEntry objects.
Permission actions defined by PERMISSION_ACTION constants of TendukeObject class are used to grant read, create, modify and delete rights for object model classes. These actions also may be used for other Permissions.
Permission has two properties that are used when granting permissions to Roles or Profiles. First, permission name defines the scope in which the Permission is used. For instance, permission name ImageEntry defines that the Permission is used to control access to ImageEntry class. A Permission must always have a unique name. Secondly, permission actions can be used for more detailed access control. For instance, in order to delete an ImageEntry object, Profile must have been granted ImageEntry permission with PERMISSION_ACTION_DELETE permission action. Using permission actions is optional, and if permission actions are not used with a given Permission, it means that granting the Permission without any permission actions is sufficient for all actions in the scope of the Permission.
PermissionChecker can be used by application developers and it is used internally in 10Duke SDK to authorize access. Permissions required by the SDK are documented in each class using PermissionChecker.
More information of authorization and permission / role management can be found on authorization and user management pages.
Storage and CDN (Content Delivery Network)
In the domain of social media applications it is usually beneficial to separate media delivered to end users from business logical data. This separation allows using CDNs (Content Delivery Networks) and storage providers like Amazon, Akamai, Voxel, Limelight etc to deliver media quickly and reliably to end users.
Within the SDK, media / file storage is accessed via StorageProvider. StorageProvider offers uniform access and management of media or files, independent of the actual storage and content delivery. In practice this means that media can be stored on and delivered from a server's local disk, or everything can be delegated to Amazon S3, or a caching CDN like Voxel can be used. In all of these cases media access and management including storing files, reading files and constructing URLs for end user media delivery uses the one and the same StorageProvider. The package containing StorageProvider interface and implementation is com.tenduke.storage.
Client using the storage provider does not need to be concerned about where files (objects) are physically stored and how to access them. Client uses a URI to identify a file for put(...) method and the file can be accessed with get(...) method using the same URI. The locate(...) method can be used to determine if a file exists for the given URI without making potentially more costly get(...) calls.
The URIs used by the storage provider to identify files use custom scheme os. URIs do not directly represent URLs and you can't call toURL() on them. In order to convert a URI to "accessible URL form", use getStandardAccessibleUri(...) method which returns a new URI which can be converted to URL for direct access to the file.
More to study
Usage, see samples
In-depth information, see storage and content delivery
Commands
The 10Duke SDK consistently uses the well-known Command pattern to encapsulate operations. The SDK provides implementation of the pattern and a distributed engine for executing the commands. This allows building very flexible and versatile systems that are distributed by nature, independent of what kind of database, storage or other components are used.
It is recommended for SDK users to encapsulate business logical processing in commands. Using commands is a neat way to package business logics and to enable distribution.
More to study:
Distribution and scaling
One of the main design drivers for the SDK is that building social media applications must be equally efficient as well in simple small-scale single-server applications as in distributed or cloud environments. Also, it is important to support scaling and moving from one deployment architecture to another (e.g. from dedicated servers to cloud).
10Duke SDK built-in distribution features address these requirements. The surface of the architecture behind SDK distribution is commands. Commands implement the Command design pattern to encapsulate data and operations so that distribution machinery can transparently carry out distribution. Commands are used in the SDK for all write type operations. Logics encapsulated this way still look simple, but allow distribution of data and operations as required by the application, in a way that is independent of databases, storage providers and deployment models. Distribution is mainly defined in com.tenduke.distribution. Command base class and CommandScheduler that is responsible for executing and distributing commands are in com.tenduke.command package.
More to study
Usage, see Samples
In-depth information, see Distribution
Tutorials
The 10Duke SDK includes a tutorial that introduces all core features in a logical order.