The document discusses web services and their encapsulation, reusability, and simplicity. It covers topics like hiding usernames/passwords, using fully qualified identifiers to locate nodes, and creating reusable classes like Asset and Property. Code examples show how to retrieve assets, work with data definition blocks, and traverse an asset tree to publish pages simply using global functions. The presentation aims to highlight best practices for web services development.

1. Web Services:
Encapsulation, Reusability, and
Simplicity
#CSUC14
Presented by
Wing Ming Chan, September 16, 2014
Upstate Medical University
chanw@upstate.edu
1

2. 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

3. Part 0: Three Questions
3

4. Purposes
 Look for positive answers
 Reveal the problems
 Highlight the main issues
4

5. 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

6. 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

7. Locating Nodes
7

8. 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

9. Part 1: Encapsulation
9

10. The Typical Way of
Starting a Program
10

11. 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

12. 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

13. Data Definitions
13

14. Data Definition Blocks
14

15. REPLACING STRUCTUREDDATA
15

16. Results
16

17. Hidden Multiple Nodes
17

18. Results
18

19. The Other Side of the Same Coin I
19

20. The Other Side of the Same Coin II
20

21. Creating a Java Error
21

22. 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?

23. 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

24. Moving Usernames and Passwords
Out of Programs:
Using Authentication Files
24

25. Authentication File Example
25

26. Password-Protected Page
26

27. Using Session
27

28. Using Command-Prompt Arguments
28

29. Authentication File:
Entry Point to Code Library
29

30. 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

31. 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

32. 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

33. 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

34. DATADEFINITIONBLOCK::GETIDENTIF
IERS
34

35. Part 2: Reusability
35

36. 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 services 36

37. 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

38. 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

39. 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

40. 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

41. 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

42. 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

43. Part 3: Simplicity
43

44. 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

45. Retrieving an Asset Object
45

46. Dumping an Asset Object
46

47. Working With
A Data Definition Block
47

48. Displaying Page-Related Information
48

49. Setting Access Rights
49

50. Setting Content Type
50

51. Switch Content Type
51

52. 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

53. ASSETTREE::TRAVERSE
53

54. ASSETTREE::APPLYFUNCTIONSTOCHIL
D
54

55. MetadataSet Associations
55

56. Global Function Used
56

57. Publishing Every Page in a Folder
57

58. AssetTree Recipes
58

59. Phantom: Episode II
 Detachment of structuredData from
dataDefinition in web services
 Created by changes of data definitions
 Affects web services only
59

60. CascadeInstances:
The Ultimate Test for Simplicity
60

61. REPORT:
ENCAPSULATING ASSETTREE
61

62. Questions?
 Tutorial: http://www.upstate.edu/cascade-admin/
projects/web-services/
 Email: chanw@upstate.edu
 A web service user group?
62