BSP Utility Classes

thomas_jung · ‎01-13-2005

Introduction

If you have done much BSP programming, I'm sure that you have ran across some of the SAP supplied utility classes. Many of the classes are named CL_BSP* or CL_HTTP*. I sat down one day recently and decided that I wanted to catalog the most useful of these classes. That's how this weblog was born. I will start it, but I am hoping the community will continue it. I have gathered information on many of these classes. I will list them here with my understanding of how they work. Most of these classes are undocumented. Therefore in many cases I had to assume how they were supposed to work by looking at SAP's use of them or by studying their inner coding. I would encourage the community to add to this list with other classes, or examples and explanations of these classes. You can add this information to the comments section or I have started a thread in the BSP forum . I will then collect all these additions and add them to the body of the Weblog. Please note that all of my examples and research were done in a WebAS 620 SP42 system.

CL_BSP_UTILITY

What a better place to start than the BSP Utility class itself. All the methods in this class are public and static.

DOWNLOAD - The first method and already I am pleasantly surprised. This method has all the coding you need to download a binary string or content as an internal table in a HTTP response object. I have seen this same coding used in examples to download Excel files. By using this method, you could avoid having to set all the response header fields yourself. The following simple little example from an OnInitialization event of page shows downloading some records from SFLIGHT as Unicode Tab Delimited.

DATA: flights TYPE flighttab,flight LIKE LINE OF flights,output TYPE string,app_type TYPE string ,l_xstring TYPE xstring.CONSTANTS: crlf TYPE string VALUE cl_abap_char_utilities=>cr_lf,tab TYPE string VALUEcl_abap_char_utilities=>

horizontal_tab.

SELECT * FROM sflight INTO TABLE flights UP TO 20 ROWS.

LOOP AT flights INTO flight.
DATA: seatsmax TYPE string.
seatsmax = flight-seatsmax.
CONDENSE seatsmax.
DATA: seatsocc TYPE string.
seatsocc = flight-seatsocc.
CONDENSE seatsocc.

CONCATENATE output
flight-carrid tab
flight-connid tab
flight-fldate tab
flight-planetype tab
seatsmax tab
seatsocc tab
crlf
INTO output.
ENDLOOP.

app_type = 'APPLICATION/MSEXCEL;charset=utf-16le'.

CALL FUNCTION 'SCMS_STRING_TO_XSTRING'
EXPORTING
    text     = output
    mimetype = 'APPLICATION/MSEXCEL;charset=utf-16le'
IMPORTING
    buffer   = l_xstring.

Add the Byte Order Mark - UTF-16 Little Endian

CONCATENATE cl_abap_char_utilities=>byte_order_mark_little
l_xstring
INTO l_xstring IN BYTE MODE.

CALL METHOD cl_bsp_utility=>download
EXPORTING
    object_s            = l_xstring
    content_type        = app_type
    content_disposition = 'attachment;filename=webforms.xls'
    response            = response
    navigation          = navigation.

CHANGE_URL - This method takes a full URL and a Relative URL and merges the two together. The explanation in the code is quite good:

*This method changes a given URL with a relative URL.

*E.G. original URL='/a/b/c.htm'

relative URL='../d/e.htm'
results in '/a/d/e.htm'

</LI>
<LI>
INSTANTIATE_DATA and INSTANTIATE_SIMPLE_DATA - These methods look like they are used to take a HTTP Form Field and create an ABAP data object to hold the corresponding data. Truthfully these methods look better left to their higher level consumers (CL_BSP_MODEL, CL_HTMLB_EVENT_TABLEVIEW, and CL_HTMLB_MANAGER). But if you want a nice example of how they work, I suggest CL_HTMLB_MANAGER, method GET_SIMPLE_DATA.
</LI>
<LI>
SERIALIZE_DATA - This method seems to be the opposite of the two we just looked at. It takes an ABAP data Object and writes it into a HTML Form Field. It's best example (and the higher level use) can be found in CL_BSP_NAVIGATION, Method SET_PARAMETER.
</LI>
<LI>
MAKE_STRING - This method takes any of ABAP's various data types and turns it into an output string. It has very similar functionality to the page->to_string( ) method. The main difference is that MAKE_STRING throws exceptions instead of issuing page messages (if_bsp_page~messages->add_message). 
<textarea rows="10" cols="79">
data: d_date type sydatum.
data: s_date type string.
d_date = sy-datum.
CALL METHOD cl_bsp_utility=>make_string
EXPORTING
 value = d_date
receiving
 output = s_date.
write: s_date.
</textarea>
</LI>
<LI>
GET_TAGLIBS - This method will scan BSP source code and report back on BSP Extension Libraries being used. This method is probably nothing more than a curiosity to the average BSP developer. This would probably only be useful if you are interested in dynamically generating BSP pages via CL_BSP_API_GENERATE.
</LI>
<LI>
DATE_TO_STRING_HTTP - This method will take an ABAP timestamp and convert it to the HTTP Header format. The use of this method comes right from method SET_BROWSER_CACHE (which we will look at in a minute). 
<textarea rows="10" cols="79">
data: ts type timestamp,
 tz type timezone value 'UTC' .
 get time stamp field ts.
 class cl_abap_tstmp definition load.
 ts = cl_abap_tstmp=>add( tstmp = ts secs = max_age ).
 convert time stamp ts time zone tz into date l_date time l_uzeit.
 time_rel(8) = l_date.
 time_rel+8(6) = l_uzeit.
 exp_value = cl_bsp_utility=>date_to_string_http( time_rel ).
</textarea>
</LI>
<LI>CREATE_PUBLIC_URL - Give this method a BSP Application and Page Name and it will create a full URL for it sitting off of the /sap/public/bsp/sap/ path. This method also adds the current language as a URI Parameter.
</LI>
<LI>
SET_BROWSER_CACHE - This method allows you to set the expiry on the Browser Cache. You can see an example in CL_BSP_CONTEXT, Method SET_CACHING.
</LI>
<LI>
GET_URI_POSITION - Definitely looks like this is for SAP internal use. There is a nice explanation at the start of the method if you are really just curious.
</LI>
<LI>
CREATE_REWRITE_URL - This method will recreate the input URL adding in a list of URI Parameters. Probably once again too low level. Most developers will probably find CL_BSP_RUNTIME, method CREATE_URL more useful.
</LI>
<LI>
UPLOAD - Obviously the opposite of the earlier DOWNLOAD method. In this case however I have always used the HTMLB element FileUpload and the CL_HTMLB_MANAGER=>GET_DATA to read the content. However I can see where this method would be useful if you weren't using the HTMLB libraries for some reason.
</LI>
<LI>
ENCODE_STRING - This is a very helpful utility that I have used many times. It allows you to encode a string for use (RAW, URL, HTML, WML, or JavaScript) inside other elements. The following is an example where I took an OTR string which happened to contain an apostrophe (test bad stuff's) and encoded it for safe use in JavaScript.
<textarea rows="8" cols="79">
<script>
 <%
data: otr_string type string.
otr_string = page->OTR_TRIM( '$TMP/mytext' ).
 %>
 alert("<%= cl_bsp_utility=>encode_string( in = otr_string encoding = if_bsp_writer=>co_javascript ).%>");
</script>
</textarea>
</LI>
</UL>

CL_HTTP_UTILITY 
CL_HTTP_UTILITY is another nice utility class with all public static methods. As we go through it, you will see that many of the methods are very similar to those in CL_BSP_UTITLITY. It seems to be heavily focused on Encoding, Decoding, and Escaping Strings. If you look at the coding, most of these methods are just wrappers for Kernel calls as well.
<UL>
<LI>
DECODE_BASE64 and ENCODE_BASE64 - The names just about say it all. These two methods decode/encode a string to Base64. I have never had a need for them myself. However there is an example of SAP's use of both methods in the class CL_BSP_VHELP_CONTROLLER.
</LI>
<LI>
ESCAPE_HTML, ESCAPE_URL, ESCAPE_WML - These methods seem to provide the same functionality as the CL_BSP_UTILITY=>ENCODE_STRING. In fact if you look at the coding of ENCODE_STRING, it just has calls to these methods. However I prefer the ENCODE_STRING because it is more concise and it also has the JavaScript encoding, which we don't have in this class.
</LI>
<LI>
UNESCAPE_URL - It is logical that if you have methods to ESCAPE a sequence, then you would also have a method to undo that escaping. That is the role this method plays.
</LI>
<LI>
STRING_TO_FIELDS and FIELDS_TO_STRING. These methods are used to put field information into the URL. This is probably more for internal SAP processing. However if you want to decode a BSP URL, you can always use the ABAP Program BSP_DECODE_URL. It is the perfect example of how to use these methods.
</LI>
<LI>
REWRITE_URL - This method is used to take input form fields and write them into the URL. This method combined with FIELDS_TO_STRING, is what SAP uses to encode fields like client, logon language, etc. and put them into the URL. I have never tried to manipulate the encoded URL directly (not sure that would be a good idea). However all of these fields can be set via their url parameter names. For instance to change the language you might just set sap-language. The following is a code sample of this.
<textarea rows="8" cols="79">
 call method cl_http_server=>append_field_url
 exporting
 name = 'sap-language'
 value = s_spras
 changing
 url = url.
 navigation->exit( url ).
</textarea>
</LI>
</UL>


CL_HTMLB_MANAGER 
This is a very important class when working with events in BSP extension libraries. I'm not going to cover every method in this class. Brian McKellar has already done an excellent job of describing the general workings of this class in the following weblog:

BSP In-Depth: Using the HTMLB Event System

CL_HTTP_SERVER

For the most part we are only interested in the Static Methods within this class. This Class represents the HTTP server itself. You will find this object as one of many public attributes in a Controller class. However these static methods have many uses. Once again we have many redundant functions between this class and the ones we have already seen.

APPEND_FIELD_URL - This is a very helpful method that allows you set or change any of SAP's special URL attributes, such as sap-language, sap-theme, etc. The following link from the SAP help specifies many of these attributes (but unfortunately not all of them). I have yet to find a source that has a complete listing.

System-Specific URL Parameters 
The following is a code sample for using this method. 
<textarea rows="8" cols="79">
 call method cl_http_server=>append_field_url
 exporting
 name = 'sap-language'
 value = s_spras
 changing
 url = url.
 navigation->exit( url ).
</textarea>
</LI>
<LI>
DECODE_BASE64 and ENCODE_BASE64 - The names just about say it all. These two methods decode/encode a string to Base64. I have never had a need for them myself. These appear to be the same as the methods in CL_HTTP_UTILITY.
</LI>
<LI>
ESCAPE_HTML and ESCAPE_URL - These methods seem to provide the same functionality as the CL_BSP_UTILITY=>ENCODE_STRING. However I prefer the ENCODE_STRING because it is more concise and it also has the JavaScript encoding, which we don't have in this class.
</LI>
<LI>
GET_EXTENSION_INFO and GET_EXTENSION_URL - These two methods return information on a particular Extension Class. They seem most useful if you were writing your own HTTP Extension Class and not very useful in the BSP context. For fun I ran these methods in test mode for the extension class, CL_HTTP_EXT_ECHO. I received back the URL position that this class is assigned to via SICF - /sap/bc/echo.
</LI>
<LI>
UNESCAPE_URL - It is logical that if you have methods to ESCAPE a sequence, then you would also have a method to undo that escaping. That is the role this method plays. Appears to serve the same purpose as the method by the same name in CL_HTTP_UTILITY.
</LI>
<LI>
GET_LOCATION and GET_LOCATION_EXCEPTION - These two methods return information (such as host name and port) for a given protocol. When I run this in my system for HTTP, I correctly get back my configured port of 80.
</LI>
<LI>
CREATE_ABS_URL and CREATE_REL_URL - These two methods are useful when assembling Absolute or Relative URLs. Perhaps you only know the path you want to link to, but you need an absolute URL. That is where CREATE_ABS_URL. It accepts PROTOCOL, HOST, PORT, PATH, and QUERYSTRING as input parameters. However these are all optional parameters, so the method can fill in the Protocol, Host, and Port for you.
</LI>
</UL>

CL_HTTP_EXT_WEBAPP 
This is a short and simple class because it just has one Static method we are interested in. Brian McKellar added the following about this method: 
Allow me one remark: cl_http_ext_webapp=>create_url_for_bsp_application is very old (ancient?). I would recommend using directly cl_bsp_runtime=>construct_bsp_url.
<UL>
<LI>
CREATE_URL_FOR_BSP_APPLICATION - This is another method that helps you create URLs. This one is different because it takes as input a BSP Application and start page. It then builds the URL given this data. I have used this method before combined with runtime->application_name to build full URLs for links to the page that is currently running. The following is an example of this.
<textarea rows="10" cols="79">
data: params type tihttpnvp.
data: url type string.
call method cl_http_ext_webapp=>create_url_for_bsp_application
exporting
bsp_application = runtime->application_name
bsp_start_page = 'dump/'
bsp_start_parameters = params
importing
abs_url = url.
</textarea>
</LI>
</UL>

CL_BSP_SERVICES 
This class has many static public methods again. Most of the methods here provide data dictionary services (such as labels and help values). These methods are especially useful thought because they work off a direct data reference.
<UL>
<LI>
GET_FIELD_LABEL and GET_QUICKINFO - Read the label or quick info for a given data reference from the data dictionary. The quick info will return the 60 character Short Text Description of a field. The Get_Field_Label will analyze the size to give either the small, medium, or large label from the data dictionary. 
<textarea rows="10" cols="79">
DATA: mandt1 TYPE symandt.
DATA: label1 TYPE string.
DATA: data_ref TYPE REF TO data.
GET REFERENCE OF mandt1 INTO data_ref.
CALL METHOD cl_bsp_services=>get_field_label
EXPORTING
 data_object_ref = data_ref
RECEIVING
 label = label1.
WRITE:/ label1.
</textarea>
</LI>
<LI>
GET_SIMPLE_HELPVALUES and GET_SIMPLE_HELPVALUES2- These methods are similar to the first two in that they import a data object reference. However these methods return a set of help values. These methods are great for returning a small set of configuration codes for a data dictionary field. The main difference between the two is the HELVALUES2 returns the key, value and Maximum value. HELPVALUES only returns the key and value. The following is a little example where I dynamically get field values for a field (described via just the field name).
<textarea rows="10" cols="79">
data: DATA_REF type string.
data_ref = 'SYMANDT'.
data: field type ref to data.
data: help1 type SHSVALTAB.
create data field type (me->data_ref).
call method cl_bsp_services=>if_bsp_services~get_simple_helpvalues
 exporting
 data_object_ref = field
 changing
 helpvalue_tab = help1.
</textarea>
</LI>
<LI>
GET_HISTORY_ID and GET_LOCAL_HISTORY_ID - Both of these methods are used to generate History IDs. Quite honestly I have never used these methods before. However it appears they fetch the ABAP Parameter ID that is attached to a field in the data dictionary. It then formatted it as such: sap.mat for field MATNR. The following was the source code I used:
<textarea rows="11" cols="79">
DATA: matnr1 TYPE matnr.
data: history type string.
DATA: data_ref TYPE REF TO data.
GET REFERENCE OF matnr1 INTO data_ref.

CALL METHOD cl_bsp_services=>get_history_id
 EXPORTING
 DATA_OBJECT_REF = data_ref
receiving
 history_id = history.
write:/ history.
</textarea>
</LI>
<LI>
GET_DAY_COLLECTION and GET_MONTH_COLLECTION - A nice little utility to return the abbreviations and names of the days of the week and months respectively.
</LI>
<LI>
GET_TABL_INFO - This method, given a data reference to a internal table, will return the structural information about it. The functions of this method are also provided by the RTTS (Run Time Type Services) classes.
</LI>
</UL>

CL_BSP_APPLICATION 
If you declare an application class for your BSP application, you are going to want to implement the IF_BSP_APPLICATION interface (and thereby inherit the functionality of the CL_BSP_APPLICATION class). Most of the methods are very straight forward and allow your BSP to query information about itself at runtime.
<UL>
<LI>
GET_APPLICATION_NAME, GET_APPLICATION_NAMESPACE, GET_APPLICATION_START_PAGE, GET_APPLICATION_THEME, GET_APPLICATION_URL - Allows you to read application settings at runtime.
</LI>
<LI>
GET_REQUEST, GET_RESPONSE, GET_RUNTIME - These methods give you pointers to the corresponding objects (Request - CL_HTTP_REQUEST, Response - CL_HTTP_RESPONSE, and the Runtime Object - CL_HTTP_RUNTIME).
</LI>
<LI>
GET_TIMEOUT, SET_TIMEOUT - For stateful applications, this allows you to read or set the timeout measured in seconds.
</LI>
<LI>
IS_STATEFUL, SET_STATEFUL - Query if your application is running stateful or dynamically switch its satefulness.
</LI>
</UL>

CL_HTTP_REQUEST 
This is the class that represents the Request data object coming from the HTTP Client. Most of the important methods in this class are going to involve reading from this request object. Outside of this normal function (which is described well in other places), I really only want to point out one additional method.
<UL>
<LI>
GET_USER_AGENT - This method will return the User Agent (which tells you what browser version your client is using). Most of the time if you are working within the HTMLB framework, this information is already available to you. However if you need to, it can be read directly from the request object.
</LI>
</UL>

CL_HTTP_RESPONSE 
The counterpart to the Request object, we have the response object. Most often we work with the response object when we want to force certain header (most common when downloading data - see CL_BSP_UTILITY=>DOWNLOAD). I should note that both the RESPONSE and REQUEST Objects have methods for manipulating Cookies at the Client side.

CL_BSP_RUNTIME 
This class represents the BSP runtime itself, so naturally there are many fun methods in it. Most are instance classes, but it isn't too difficult to get a reference to the runtime from MVC, Pages, or BSP Extensions.
<UL>
<LI>
CONSTRUCT_BSP_URL - Static Method for building the full URL given the BSP Application name (and other optional parameters). Very similar in function to cl_http_ext_webapp=>create_url_for_bsp_application.
</LI>
<LI>
GET_OTR_TEXT - Ever wanted to read a particular OTR text programmatically? This is the method to do it. Give it the alias and it will return the text string back to you. What could be easier?
</LI>
<LI>
WITH_ACCESSIBILITY and SET_ACCESSIBILITY - These methods allows you read the status of or set the Accessibility flag. This attribute can also be set via URL parameter: sap-accessibility. 
The following is an example of reading the accessibility flag from within a BSP Extension:
<textarea rows="3" cols="79">
****Read the current value of the Accessiblity flag from the Runtime Object
clear s_accessibility.
s_accessibility = mc_runtime->with_accessibility( ).
</textarea>
</LI>
<LI>
WITH_RIGHT_TO_LEFT - Similar to the WITH_ACCESSIBILITY method, except that it returns the current status of the Right to Left status. This flag (RTL) is the special setting for languages that read from Right to Left (such as Hebrew and Arabic).
</LI>
<LI>
GET_URL - Get the URL for the current Page. Nuf said!
</LI>
<LI>
GET_DOMAIN_RELAX_SCRIPT - Have you ever had to include the Domain Relaxation Script in your page? This is the method that will write that script into the page for you. Most often you see included directly in a page or View just like the following: 
<textarea rows="2" cols="79">
<%= runtime->GET_DOMAIN_RELAX_SCRIPT( ) %>
</textarea>
</LI>
<LI>
GET_URL_SAME_SESSION, GET_URL_STATELESS, GET_URL_NEW_SESSION - These generate URLs for BSP applications that either will run in the same session as the current application, Statelessly, or Stateful but in a new session. The explanation from the coding itself helps to make sense of the difference between these three methods:

The difference between these three methods makes only sense when the session
id is transported via URL. This is true, if the application is called with the
parameter "sap-syscmd=nocookie", or if it is called from the portal.

CL_BSP_NAVIGATION

Just like its name suggests this class, that represents the navigation object, is concerned with navigation from page to page and application to application. Most of the methods are quite explanatory. I didn't really find anything that just jumped out at me. Of course you have methods such as EXIT, GOTO_PAGE, NEXT_PAGE, SET_PARAMETER, and RESPONSE_COMPLETE. Maybe I am just getting tired, but I don't see a whole lot of value in cataloging such basic navigation methods. Perhaps this is an area that someone else wants to expand upon.

CL_BSP_PAGE

This classes represents the page object itself. As you look through the methods in this class (most of which are inherited from IF_BSP_PAGE), you will see that many of them are duplicates of those within CL_BSP_APPLICATION.

GET_APPLICATION_NAME, GET_APPLICATION_NAMESPACE, GET_APPLICATION_START_PAGE, GET_APPLICATION_THEME, GET_APPLICATION_URL - Allows you to read application settings at runtime.
GET_REQUEST, GET_RESPONSE, GET_RUNTIME - These methods give you pointers to the corresponding objects (Request - CL_HTTP_REQUEST, Response - CL_HTTP_RESPONSE, and the Runtime Object - CL_HTTP_RUNTIME).
OTR_TRIM - Another Method that will read OTR Texts. Similar to CL_BSP_RUNTIME=>GET_OTR_TEXT.
GET_PAGE_NAME and GET_PAGE_URL - Read the name or URL of a Page at runtime.
TO_STRING - A nice little method that will take a field of type any and write it out as a string. This is especially useful for outputting Dates, Times, Currency Amounts, etc.

CL_BSP_API_GENERATE

I stumbled across this class as I was creating this weblog. It looks like a full API to generate BSP applications dynamically. Brian McKellar confirmed this recently with the following statement: And then, for those that can not help themselves, and insist on generating their own BSP applications: CL_BSP_API_GENERATE. I didn't get any hits on this class on OSS. I have no idea if SAP intends for customers to use this class. It looks complex enough that I don't want to try to go into the details here. Perhaps this is a complete topic of its own for another time.

CL_BSP_MESSAGES

This entire section was contributed by Ariel Ferreiro . Thank you for this very nice addition of the BSP Message Class.

ADD_MESSAGE - insert a new message into the message list. If the message is already into the list is is overwritten. Sample:

ADDING A MESSAGE

IF SY-SUBRC EQ 0.
page->messages->add_message(
condition = 'mtv'
message = 'File uploaded succesfully'
severity = page->messages->co_severity_info ).
ENDIF.

Sending E-Mail from ABAP - Version 610 and Higher - BCS Interface

CL_BSP_SERVER_SIDE_COOKIE

This section was submitted by Brian McKellar on 1/23/2005. Thanks.

Then let me add CL_BSP_SERVER_SIDE_COOKIE. This is really an absolute bread-and-butter class for anyone considering to write high scalable applications (always stateless and leave everything in the server).

CL_MIME_REPOSITORY_API

Another fine addition by Brian McKellar.

There are times that people would like to get stuff in and out of the MIME repository. Here a colleague wrote an excellent API (after one has tried to mess with LOIOs!): IF_MR_API and CL_MIME_REPOSITORY_API (I can not remember if we did port this down onto 640). - Note by Tom Jung: I checked my 640 SP10 system and my 620 SP42 system and I did have this class in both. It looks very nice.

CL_HTTP_EXT_BASE_HANDLER

Also an addition by Brian McKellar.

My personal favourite is CL_HTTP_EXT_BASE_HANDLER. This is the place where rubber meets the road and your first web service is done in 15 minutes. This is a base class that I use often to quickly write test programs with. See also: BSP In-Depth: Writing an HTTP Handler.

IF_HTTP_HEADER_FIELDS and IF_HTTP_FORM_FIELDS

Another submission by Brian McKellar.

There are a few more interfaces that I would like to recommend: IF_HTTP_HEADER_FIELDS (& SAP) and IFHTTP_FORM_FIELDS (& SAP). These interfaces contains constant strings of all header/form fields that we regularly use. It prevents typing mistakes like "ContentDisposition". Typical examples:

CLOSING

I'm sure that I have missed some methods and even entire classes. Feel free to add this information in the comments or in the related Forum Posting. I will make sure that this weblog gets updated with the information.

BSP Utility Classes

Now live: 2014 SAP HANA and SAP HANA Cloud Applications Challenge voting

My Personal Ux, Fiori, Portal and Cloud Cheat Sheet

Web Dynpro ABAP Demonstration Videos