Web Services:Encapsulation, Reusability, and Simplicity

#CSUC14

Presented by

Wing Ming Chan, September 16, 2014

Upstate Medical University

chanw@upstate.edu

1

Topics

Encapsulation: data and data manipulation hiding Usernames and passwords Creating phantom entities in Cascade Fully qualified identifiers

Reusability: code ready to use without modification AssetOperationHandlerService Asset and Property classes

Simplicity: lines of code Cascade and AssetTree classes CascadeInstances and Report classes

2

Part 0: Three Questions

3

Purposes

Look for positive answers Reveal the problems Highlight the main issues

4

Question 1

How many of you can write a web service program, doing something, anything, without hard-coding the username and password anywhere in your code?

Main concern Security and encapsulation of sensitive data Access restrictions

5

Question 2

How many of you can work with the first node of the second multiple field in a data definition block, without looking at the read dump of the block? Can you hard-code the location of the node in you program?

Main concern Encapsulation and reusability

6

Locating Nodes

7

Question 3

Besides the use of require_once or include_once, how many of you can use a single semi-colon in your code to do the following: Associate metadata set 1 with all folders in a site

(including Base Folder) Associate metadata set 2 with all files in the site Associate metadata set 3 with all symlinks in the site

Requirements: no program-specific data allowed in the required/included files; all information related to metadata sets, folders, files, and symlinks must show up in your code

Main concerns Reusability and simplicity

8

Part 1: Encapsulation

9

The Typical Way of Starting a Program

10

Problems?

Programs are tied with usernames, passwords, and WSDL URL’s People can come and go Changes of passwords URL’s can change too (different instances)

Passwords exposed Security

A single program used by multiple users Usernames and passwords change depending on

the users using the same program Access restrictions

11

Phantom: Episode I

Detachment of structuredData from dataDefinition in web services Created by web services Only affects data definition blocks (including

those plugged into pages) Can be created in pages, but haven’t figure out a

way to reveal the hidden content

12

Data Definitions

13

Data Definition Blocks

14

REPLACING STRUCTUREDDATA

15

Results

16

Hidden Multiple Nodes

17

Results

18

The Other Side of the Same Coin I

19

The Other Side of the Same Coin II

20

Creating a Java Error

21

A NIGHTMARE…

22

Pretend that I am you enemy What I can do to you:

Detachment of data definitions from content types

Assigning an empty string to a checkbox in data definition blocks

Data definition manipulation with phantom nodes How long will it take to solve the problem:

Days? Weeks?

Encapsulating Usernames and Passwords: a Two-Step Approach

Step 1: move usernames and passwords out of programs to authentication files

Step 2: hide usernames and passwords from the system altogether

23

Moving Usernames and PasswordsOut of Programs: Using Authentication Files

24

Authentication File Example

25

Password-Protected Page

26

Using Session

27

Using Command-Prompt Arguments

28

Authentication File: Entry Point to Code Library

29

The AssetOperationHandlerService Class: Encapsulating Operations

Encapsulation Username and password URL The SoapClient object and all operations All parameters required for operations

The instance $service: Instantiated in the authentication files Passed from client code to code library Performs all basic operations in code library

30

Fully Qualified Identifiers

When working with data definition blocks or pages, we need to work with nodes

A fully qualified identifier of a node is the full path of the node, including all the information about ancestors and absolute position

Example: pie;1;pie-is-sliced

31

What Is Special About Fully Qualified Identifiers

Example: pie;1;pie-is-sliced The ;1 part following an identifier indicates

that the field is a multiple field ;0 means that the node bearing this

identifier is the first node in the set; ;1 means that the node is the second node of the set

Unlike array indexes, the fully qualified identifier of a node never changes, no matter how many cousins and siblings it has

A more complicated example: main-field;group;2;sub-group;1;text;3

32

Why Fully Qualified Identifiers?

They never change: can be hard-coded in programs

Easy node look-up Possible to use for and foreach loops Encapsulation of arrays and stdClass

objects

33

DATADEFINITIONBLOCK::GETIDENTIFIERS

34

Part 2: Reusability

35

Why OOP?

Encapsulation Hiding complicated program logic Hiding data and raw data structures

Reusability The entire library consists of reusable code Easy object retrieval Providing look-up mechanism Setting and editing data and metadata, and

preventing unacceptable input Error checking and exception handling Inheritance

Problems with web services36

Problems with Web Services I

It is possible to delete the value of a required field using web services (e.g. in a metadata set)

Cascade won’t complain when an unacceptable boolean value is assigned to a field (e.g. fals instead of false) An unacceptable boolean value is ignored Unlike dateTime (which is represented by an object)

Cascade won’t complain when an unacceptable string value is assigned to a dropdown An undefined item is introduced An empty string will also work

37

Problems with Web Services II

When a single-item checkbox is assigned an empty string, Cascade won’t complain

However, the associated data definition block cannot be viewed (a Java error)

The field should have been assigned the string ‘::CONTENT-XML-CHECKBOX::’ instead

Phantoms we have met

38

Problems with Web Services III

Assignment of NULL vs. unset When modifying temporal settings for scheduled

publishing (for a site, a publish set, or a destination), assignments of the NULL value to properties won’t work

Instead, we must unset the properties

39

ASSET AND PROPERTY

Asset: an abstract class Other abstract subclasses: ContainedAsset, Container, Block, Format, etc.

42 concrete classes corresponding to 42 asset types defined in the WSDL

All methods have returned values Method chaining possible

stdClass objects within an asset are represented by subclasses of Property

40

Inheritance

Reusability An asset class can be reused to deal with any

assets of the same type Metadata-related classes can be reused in File, Page, Block (and its subclasses), Format (and its subclasses) and Symlink

Members in a parent class inherited by child classes, avoiding repetition of code

Separate code files Less code per file Easier to maintain

41

Exception Handling

All classes throw exceptions of various types Client code is expected to deal with

exceptions Two modes of execution: strict and lenient To throw or not to throw? Cascade::getAsset vs. Cascade::getX (e.g. Cascade::getPage)

42

Part 3: Simplicity

43

Writing Client Code

Client code does not look like ‘normal’ Cascade web service code No username and password No arrays of raw data or stdClass objects Chained method calls Handling of exceptions A lot shorter: simplicity!

Normally, no use of new keyword Easy retrieval of asset objects Easy retrieval of associated objects of pages High level classes: Cascade and AssetTree 44

Retrieving an Asset Object

45

Dumping an Asset Object

46

Working With A Data Definition Block

47

Displaying Page-Related Information

48

Setting Access Rights

49

Setting Content Type

50

Switch Content Type

51

ASSETTREE

A tree structure consisting of: Root container Children Sub-trees

What it is good for: Creating reports Modifying assets of a certain type or types

The AssetTree::traverse method Visits the root, every children of the root, and recursively

all sub-trees (depth-first traversal) Accepts global functions, parameters, and results array

(passed in by reference) Global functions as filters 52

ASSETTREE::TRAVERSE

53

ASSETTREE::APPLYFUNCTIONSTOCHILD

54

MetadataSet Associations

55

Global Function Used

56

Publishing Every Page in a Folder

57

AssetTree Recipes

58

Phantom: Episode II

Detachment of structuredData from dataDefinition in web services Created by changes of data definitions Affects web services only

59

CascadeInstances:The Ultimate Test for Simplicity

60

REPORT:ENCAPSULATING ASSETTREE

61

Questions?

Tutorial: http://www.upstate.edu/cascade-admin/projects/web-services/

Email: chanw@upstate.edu A web service user group?

62